@agentica/core 0.45.0-dev.20260426 → 0.45.1

package/src/orchestrate/cancel.ts

@@ -1,6 +1,8 @@
+import type { IJsonParseResult } from "@typia/interface";
 import type OpenAI from "openai";
 import type { ILlmFunction, IValidation } from "typia";
 
+import { dedent, LlmJson } from "@typia/utils";
 import typia from "typia";
 
 import type { AgenticaContext } from "../context/AgenticaContext";
@@ -25,11 +27,19 @@ const FUNCTION: ILlmFunction = typia.llm.application<
   __IChatCancelFunctionsApplication
 >().functions[0]!;
 
-interface IFailure {
-  id: string;
-  name: string;
-  validation: IValidation.IFailure;
-}
+type IFailure
+  = | {
+    kind: "parse";
+    id: string;
+    name: string;
+    failure: IJsonParseResult.IFailure;
+  }
+  | {
+    kind: "validation";
+    id: string;
+    name: string;
+    validation: IValidation.IFailure;
+  };
 
 export async function cancel(
   ctx: AgenticaContext,
@@ -185,15 +195,56 @@ async function step(
           continue;
         }
 
-        const input: object = FUNCTION.parse(tc.function.arguments) as object;
+        // LENIENT JSON PARSING
+        //
+        // A malformed JSON string is reported back to the LLM as a parse
+        // failure, mirroring `call.ts`. On success the parsed `.data` (never
+        // the `IJsonParseResult` wrapper itself) is forwarded to validation.
+        const parsed: IJsonParseResult<unknown> = FUNCTION.parse(
+          tc.function.arguments,
+        );
+        if (parsed.success === false) {
+          failures.push({
+            kind: "parse",
+            id: tc.id,
+            name: tc.function.name,
+            failure: parsed,
+          });
+          continue;
+        }
         const validation: IValidation<__IChatFunctionReference.IProps>
-          = FUNCTION.validate(input) as IValidation<__IChatFunctionReference.IProps>;
+          = FUNCTION.validate(parsed.data) as IValidation<__IChatFunctionReference.IProps>;
         if (validation.success === false) {
           failures.push({
+            kind: "validation",
             id: tc.id,
             name: tc.function.name,
             validation,
           });
+          continue;
+        }
+
+        // FUNCTION EXISTENCE
+        //
+        // `typia` only proves that `name` is a `string`; it cannot know which
+        // functions are currently selected. A name that is not stacked would
+        // otherwise be silently dropped by `cancelFunctionFromContext`, so
+        // report it back to the LLM as an `IValidation.IFailure`.
+        const referenceErrors: IValidation.IError[] = validateFunctionExistence(
+          ctx,
+          validation.data,
+        );
+        if (referenceErrors.length > 0) {
+          failures.push({
+            kind: "validation",
+            id: tc.id,
+            name: tc.function.name,
+            validation: {
+              success: false,
+              data: validation.data,
+              errors: referenceErrors,
+            },
+          });
         }
       }
     }
@@ -217,15 +268,18 @@ async function step(
           continue;
         }
 
-        const input: __IChatFunctionReference.IProps | null
-          = typia.json.isParse<
-            __IChatFunctionReference.IProps
-          >(tc.function.arguments);
-        if (input === null) {
+        // Reuse the lenient parser + validator so that arguments accepted
+        // by the VALIDATION retry above are processed consistently here.
+        const parsed: IJsonParseResult<unknown> = FUNCTION.parse(
+          tc.function.arguments,
+        );
+        const validation: IValidation<__IChatFunctionReference.IProps>
+          = FUNCTION.validate(parsed.data) as IValidation<__IChatFunctionReference.IProps>;
+        if (validation.success === false) {
           continue;
         }
 
-        for (const reference of input.functions) {
+        for (const reference of validation.data.functions) {
           cancelFunctionFromContext(
             ctx,
             reference,
@@ -240,32 +294,92 @@ async function step(
 function emendMessages(failures: IFailure[]): OpenAI.ChatCompletionMessageParam[] {
   return failures
     .map(f => [
-        {
-          role: "assistant",
-          tool_calls: [
-            {
-              type: "function",
-              id: f.id,
-              function: {
-                name: f.name,
-                arguments: JSON.stringify(f.validation.data),
-              },
+      {
+        role: "assistant",
+        tool_calls: [
+          {
+            type: "function",
+            id: f.id,
+            function: {
+              name: f.name,
+              arguments: f.kind === "parse"
+                ? f.failure.input
+                : JSON.stringify(f.validation.data),
             },
-          ],
-        } satisfies OpenAI.ChatCompletionAssistantMessageParam,
-        {
-          role: "tool",
-          content: JSON.stringify(f.validation.errors),
-          tool_call_id: f.id,
-        } satisfies OpenAI.ChatCompletionToolMessageParam,
-        {
-          role: "system",
-          content: [
-            "You A.I. assistant has composed wrong typed arguments.",
-            "",
-            "Correct it at the next function calling.",
-          ].join("\n"),
-        } satisfies OpenAI.ChatCompletionSystemMessageParam,
+          },
+        ],
+      } satisfies OpenAI.ChatCompletionAssistantMessageParam,
+      {
+        role: "tool",
+        tool_call_id: f.id,
+        content: f.kind === "parse"
+          ? dedent`
+              Invalid JSON format.
+
+              Here is the detailed parsing failure information,
+              including error messages and their locations within the input:
+
+              \`\`\`json
+              ${JSON.stringify(f.failure.errors)}
+              \`\`\`
+
+              And here is the partially parsed data that was successfully
+              extracted before the error occurred:
+
+              \`\`\`json
+              ${JSON.stringify(f.failure.data)}
+              \`\`\`
+            `
+          : [
+              "🚨 VALIDATION FAILURE: Your function arguments do not conform to the required schema.",
+              "",
+              "Each error below is computed absolute truth from rigorous type validation.",
+              "You must fix ALL errors to achieve 100% schema compliance.",
+              "",
+              LlmJson.stringify(f.validation),
+            ].join("\n"),
+      } satisfies OpenAI.ChatCompletionToolMessageParam,
+      {
+        role: "system",
+        content: f.kind === "parse"
+          ? AgenticaSystemPrompt.JSON_PARSE_ERROR.replace(
+              "${{FAILURE}}",
+              JSON.stringify(f.failure),
+            )
+          : AgenticaSystemPrompt.VALIDATE,
+      } satisfies OpenAI.ChatCompletionSystemMessageParam,
     ])
     .flat();
 }
+
+/**
+ * Validate that every function to cancel is actually selected right now.
+ *
+ * `typia` validation only proves that `__IChatFunctionReference.name` is a
+ * `string`; it cannot know which functions are currently stacked. Without this
+ * check a name that is not selected would be silently dropped by
+ * `cancelFunctionFromContext`. The returned errors are fed back to the LLM
+ * through `emendMessages`, exactly like a type validation error - with the
+ * list of cancellable function names in `expected`.
+ */
+function validateFunctionExistence(
+  ctx: AgenticaContext,
+  data: __IChatFunctionReference.IProps,
+): IValidation.IError[] {
+  const cancellable: string[] = ctx.stack.map(s => s.operation.name);
+  const expected: string = cancellable.length === 0
+    ? "never"
+    : cancellable.map(name => JSON.stringify(name)).join(" | ");
+  return data.functions.flatMap((reference, i): IValidation.IError[] =>
+    cancellable.includes(reference.name)
+      ? []
+      : [{
+          path: `$input.functions[${i}].name`,
+          expected,
+          value: reference.name,
+          description: cancellable.length === 0
+            ? `Function "${reference.name}" cannot be cancelled because no function is currently selected.`
+            : `Function "${reference.name}" is not in the current selection, so it cannot be cancelled.`,
+        }],
+  );
+}

package/src/orchestrate/select.ts

@@ -1,6 +1,8 @@
+import type { IJsonParseResult } from "@typia/interface";
 import type OpenAI from "openai";
 import type { ILlmFunction, IValidation } from "typia";
 
+import { dedent, LlmJson } from "@typia/utils";
 import typia from "typia";
 
 import type { AgenticaContext } from "../context/AgenticaContext";
@@ -28,11 +30,19 @@ const FUNCTION: ILlmFunction = typia.llm.application<
   __IChatSelectFunctionsApplication
 >().functions[0]!;
 
-interface IFailure {
-  id: string;
-  name: string;
-  validation: IValidation.IFailure;
-}
+type IFailure
+  = | {
+    kind: "parse";
+    id: string;
+    name: string;
+    failure: IJsonParseResult.IFailure;
+  }
+  | {
+    kind: "validation";
+    id: string;
+    name: string;
+    validation: IValidation.IFailure;
+  };
 
 export async function select(
   ctx: AgenticaContext,
@@ -241,15 +251,57 @@ async function step(
         if (tc.type !== "function" || tc.function.name !== "selectFunctions") {
           continue;
         }
-        const input: object = FUNCTION.parse(tc.function.arguments) as object;
+        // LENIENT JSON PARSING
+        //
+        // A malformed JSON string is reported back to the LLM as a parse
+        // failure, mirroring `call.ts`. On success the parsed `.data` (never
+        // the `IJsonParseResult` wrapper itself) is forwarded to validation.
+        const parsed: IJsonParseResult<unknown> = FUNCTION.parse(
+          tc.function.arguments,
+        );
+        if (parsed.success === false) {
+          failures.push({
+            kind: "parse",
+            id: tc.id,
+            name: tc.function.name,
+            failure: parsed,
+          });
+          continue;
+        }
         const validation: IValidation<__IChatFunctionReference.IProps>
-          = FUNCTION.validate(input) as IValidation<__IChatFunctionReference.IProps>;
+          = FUNCTION.validate(parsed.data) as IValidation<__IChatFunctionReference.IProps>;
         if (validation.success === false) {
           failures.push({
+            kind: "validation",
             id: tc.id,
             name: tc.function.name,
             validation,
           });
+          continue;
+        }
+
+        // FUNCTION EXISTENCE
+        //
+        // `typia` only proves that `name` is a `string`; it cannot know which
+        // functions exist at runtime. A hallucinated name would otherwise be
+        // silently dropped by `selectFunctionFromContext`, so report it back
+        // to the LLM as an `IValidation.IFailure`, just like a type error.
+        const referenceErrors: IValidation.IError[] = validateFunctionExistence(
+          ctx,
+          operations,
+          validation.data,
+        );
+        if (referenceErrors.length > 0) {
+          failures.push({
+            kind: "validation",
+            id: tc.id,
+            name: tc.function.name,
+            validation: {
+              success: false,
+              data: validation.data,
+              errors: referenceErrors,
+            },
+          });
         }
       }
     }
@@ -273,14 +325,17 @@ async function step(
           continue;
         }
 
-        const input: __IChatFunctionReference.IProps | null
-          = typia.json.isParse<__IChatFunctionReference.IProps>(
-            tc.function.arguments,
-          );
-        if (input === null) {
+        // Reuse the lenient parser + validator so that arguments accepted
+        // by the VALIDATION retry above are processed consistently here.
+        const parsed: IJsonParseResult<unknown> = FUNCTION.parse(
+          tc.function.arguments,
+        );
+        const validation: IValidation<__IChatFunctionReference.IProps>
+          = FUNCTION.validate(parsed.data) as IValidation<__IChatFunctionReference.IProps>;
+        if (validation.success === false) {
           continue;
         }
-        for (const reference of input.functions) {
+        for (const reference of validation.data.functions) {
           selectFunctionFromContext(
             ctx,
             reference,
@@ -303,24 +358,85 @@ function emendMessages(failures: IFailure[]): OpenAI.ChatCompletionMessageParam[
             id: f.id,
             function: {
               name: f.name,
-              arguments: JSON.stringify(f.validation.data),
+              arguments: f.kind === "parse"
+                ? f.failure.input
+                : JSON.stringify(f.validation.data),
             },
           },
         ],
       } satisfies OpenAI.ChatCompletionAssistantMessageParam,
       {
         role: "tool",
-        content: JSON.stringify(f.validation.errors),
         tool_call_id: f.id,
+        content: f.kind === "parse"
+          ? dedent`
+              Invalid JSON format.
+
+              Here is the detailed parsing failure information,
+              including error messages and their locations within the input:
+
+              \`\`\`json
+              ${JSON.stringify(f.failure.errors)}
+              \`\`\`
+
+              And here is the partially parsed data that was successfully
+              extracted before the error occurred:
+
+              \`\`\`json
+              ${JSON.stringify(f.failure.data)}
+              \`\`\`
+            `
+          : [
+              "🚨 VALIDATION FAILURE: Your function arguments do not conform to the required schema.",
+              "",
+              "Each error below is computed absolute truth from rigorous type validation.",
+              "You must fix ALL errors to achieve 100% schema compliance.",
+              "",
+              LlmJson.stringify(f.validation),
+            ].join("\n"),
       } satisfies OpenAI.ChatCompletionToolMessageParam,
       {
         role: "system",
-        content: [
-          "You A.I. assistant has composed wrong typed arguments.",
-          "",
-          "Correct it at the next function calling.",
-        ].join("\n"),
+        content: f.kind === "parse"
+          ? AgenticaSystemPrompt.JSON_PARSE_ERROR.replace(
+              "${{FAILURE}}",
+              JSON.stringify(f.failure),
+            )
+          : AgenticaSystemPrompt.VALIDATE,
       } satisfies OpenAI.ChatCompletionSystemMessageParam,
     ])
     .flat();
 }
+
+/**
+ * Validate that every selected function actually exists.
+ *
+ * `typia` validation only proves that `__IChatFunctionReference.name` is a
+ * `string`; it cannot know which functions exist at runtime. Without this
+ * check a hallucinated name would be silently dropped by
+ * `selectFunctionFromContext`. The returned errors are fed back to the LLM
+ * through `emendMessages`, exactly like a type validation error - with the
+ * list of valid function names in `expected`.
+ */
+function validateFunctionExistence(
+  ctx: AgenticaContext,
+  candidates: AgenticaOperation[],
+  data: __IChatFunctionReference.IProps,
+): IValidation.IError[] {
+  const expected: string = candidates
+    .map(op => JSON.stringify(op.name))
+    .join(" | ");
+  return data.functions.flatMap((reference, i): IValidation.IError[] =>
+    ctx.operations.flat.has(reference.name)
+      ? []
+      : [{
+          path: `$input.functions[${i}].name`,
+          expected,
+          value: reference.name,
+          description: [
+            `Function "${reference.name}" does not exist.`,
+            "Select only from the functions provided by getApiFunctions().",
+          ].join(" "),
+        }],
+  );
+}

package/src/utils/ChatGptCompletionMessageUtil.ts

@@ -95,13 +95,13 @@ function accumulate(origin: ChatCompletion, chunk: ChatCompletionChunk): ChatCom
   };
 }
 
-function merge(chunks: ChatCompletionChunk[]): ChatCompletion {
+function mergeChunks(chunks: ChatCompletionChunk[]): ChatCompletion {
   const firstChunk = chunks[0];
   if (firstChunk === undefined) {
     throw new Error("No chunks received");
   }
 
-  const result = chunks.reduce(accumulate, {
+  return chunks.reduce(accumulate, {
     id: firstChunk.id,
     choices: [],
     created: firstChunk.created,
@@ -111,17 +111,29 @@ function merge(chunks: ChatCompletionChunk[]): ChatCompletion {
     service_tier: firstChunk.service_tier,
     system_fingerprint: firstChunk.system_fingerprint,
   } as ChatCompletion);
+}
 
-  // post-process
-  result.choices?.forEach((choice) => {
+/**
+ * Replace any tool call's empty `arguments` with `"{}"`.
+ *
+ * MUST only be applied to a final, fully streamed completion. Running it while
+ * more chunks may still arrive would seed `"{}"` into a not-yet-complete tool
+ * call, and the remaining streamed argument chunks would then be appended onto
+ * it - corrupting the arguments into `{}{...}`.
+ */
+function fixEmptyToolArguments(completion: ChatCompletion): ChatCompletion {
+  completion.choices?.forEach((choice) => {
     choice.message.tool_calls?.filter(tc => tc.type === "function").forEach((toolCall) => {
       if (toolCall.function.arguments === "") {
         toolCall.function.arguments = "{}";
       }
     });
   });
+  return completion;
+}
 
-  return result;
+function merge(chunks: ChatCompletionChunk[]): ChatCompletion {
+  return fixEmptyToolArguments(mergeChunks(chunks));
 }
 
 function mergeChoice(acc: ChatCompletion.Choice, cur: ChatCompletionChunk.Choice): ChatCompletion.Choice {
@@ -221,6 +233,8 @@ export const ChatGptCompletionMessageUtil = {
   transformCompletionChunk,
   accumulate,
   merge,
+  mergeChunks,
+  fixEmptyToolArguments,
   mergeChoice,
   mergeToolCalls,
 };

package/src/utils/ChatGptCompletionStreamingUtil.ts

@@ -56,7 +56,11 @@ async function reduceStreamingWithDispatch(stream: ReadableStream<ChatCompletion
     };
     if (acc.object === "chat.completion.chunk") {
       registerContext([acc, chunk].flatMap(v => v.choices ?? []));
-      return ChatGptCompletionMessageUtil.merge([acc, chunk]);
+      // Use `mergeChunks`, NOT `merge`: `merge` runs the empty-arguments
+      // fixup, which mid-stream seeds a still-incomplete tool call with "{}"
+      // so the remaining streamed argument chunks append onto it (`{}{...}`).
+      // The fixup is applied once, to the final completion, below.
+      return ChatGptCompletionMessageUtil.mergeChunks([acc, chunk]);
     }
     registerContext(chunk.choices ?? []);
     return ChatGptCompletionMessageUtil.accumulate(acc, chunk);
@@ -85,7 +89,7 @@ async function reduceStreamingWithDispatch(stream: ReadableStream<ChatCompletion
     });
     return completion;
   }
-  return nullableCompletion;
+  return ChatGptCompletionMessageUtil.fixEmptyToolArguments(nullableCompletion);
 }
 
 export { reduceStreamingWithDispatch };