fix(kernel-agents): use external json parsing (#853)

## Summary

- Replace the bracket-counting heuristic in `sample-collector.ts` with
the
[`partial-json`](https://github.com/promplate/partial-json-parser-js)
library to correctly distinguish incomplete-but-valid JSON from
malformed JSON during LLM streaming
- Fix false positives when streamed JSON contains brace characters
inside string values (e.g. `{"think": "add a '}' here"}`)
- Use `Allow.OBJ` to reject non-object partial JSON early
- Wrap all `partial-json` errors in `SampleGenerationError` for
consistent error handling

Closes #673 

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes core streaming-response parsing behavior, which can alter
when/why `SampleGenerationError` is thrown and may affect downstream
agent flows; impact is contained to JSON strategy parsing and is
test-covered.
> 
> **Overview**
> Replaces the `makeSampleCollector` streaming JSON parsing heuristic
(brace counting + `JSON.parse`) with `partial-json` to distinguish
**complete**, **incomplete**, and **malformed** buffers during LLM
streaming, and to avoid false failures when braces appear inside string
values.
> 
> Adds `partial-json` as a dependency and updates tests to reflect the
new error behavior (earlier rejection of non-JSON text, adjusted
max-chunk test input, and new coverage for braces-in-string handling).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
418cc32. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: grypez

packages/kernel-agents/package.json

@@ -187,6 +187,7 @@
     "@metamask/kernel-utils": "workspace:^",
     "@metamask/logger": "workspace:^",
     "@ocap/kernel-language-model-service": "workspace:^",
+    "partial-json": "^0.1.7",
     "ses": "^1.14.0"
   }
 }

packages/kernel-agents/src/strategies/json/sample-collector.test.ts

@@ -48,24 +48,24 @@ describe('makeSampleCollector', () => {
     );
   });
 
-  it('throws error for invalid JSON', () => {
-    const invalidJson = '{"invalid": json}';
+  it('throws error for malformed JSON', () => {
     const collector = makeSampleCollector({});
-    expect(() => collector(invalidJson)).toThrow(
+    expect(() => collector('not json at all')).toThrow(
       expect.objectContaining({
         message: 'LLM generated invalid response.',
         cause: expect.objectContaining({
-          message: expect.stringContaining(invalidJson),
+          message: expect.stringContaining('at position'),
         }),
       }),
     );
   });
 
   it('throws error when max chunk count exceeded', () => {
     const collector = makeSampleCollector({ maxChunkCount: 2 });
-    collector('chunk1');
-    collector('chunk2');
-    expect(() => collector('chunk3')).toThrow(
+    // Use valid partial JSON so partial-json does not flag it early
+    collector('{"key": "');
+    collector('aaa');
+    expect(() => collector('bbb')).toThrow(
       expect.objectContaining({
         message: 'LLM generated invalid response.',
         cause: expect.objectContaining({
@@ -74,4 +74,27 @@ describe('makeSampleCollector', () => {
       }),
     );
   });
+
+  it('handles braces inside string values without false errors', () => {
+    const collector = makeSampleCollector({});
+    // Simulates an LLM streaming: { think: "I should add a '}' to the..."
+    // The old bracket-counting heuristic would false-positive here because
+    // the '}' inside the string balances the opening brace.
+    expect(collector('{"think": "I should add a ')).toBeNull();
+    expect(collector("'}' to the")).toBeNull();
+    expect(collector(' response", "done": true}')).toStrictEqual({
+      think: "I should add a '}' to the response",
+      done: true,
+    });
+  });
+
+  it('detects genuinely malformed JSON early', () => {
+    const collector = makeSampleCollector({ maxChunkCount: 100 });
+    // Bare text is structurally invalid — partial-json detects this immediately
+    expect(() => collector('this is not json')).toThrow(
+      expect.objectContaining({
+        message: 'LLM generated invalid response.',
+      }),
+    );
+  });
 });

packages/kernel-agents/src/strategies/json/sample-collector.ts

@@ -1,10 +1,16 @@
 import { SampleGenerationError } from '@metamask/kernel-errors';
 import type { Logger } from '@metamask/logger';
+import { parse, MalformedJSON, PartialJSON } from 'partial-json';
 
 import type { SampleCollector } from '../../types.ts';
 
 /**
- * A quick and dirty sample collector for a streaming response.
+ * A sample collector for a streaming JSON object response.
+ *
+ * Uses `partial-json` for a three-way check on each chunk:
+ * - **Complete** — `parse(buffer, 0)` returns the parsed object.
+ * - **Incomplete** — throws `PartialJSON`, meaning the buffer is valid so far.
+ * - **Malformed** — throws `MalformedJSON`, meaning the buffer is irrecoverable.
  *
  * @param args - The arguments to make the sample collector.
  * @param args.prefix - The prefix to prepend to the response
@@ -24,36 +30,25 @@ export const makeSampleCollector = <Result = unknown>({
 }): SampleCollector<Result> => {
   let response = prefix;
   let chunkCount = 0;
-  let leftBracketCount = prefix.split('{').length - 1;
-  let rightBracketCount = prefix.split('}').length - 1;
   return (delta: string) => {
     chunkCount += 1;
-    const subchunks = delta.split('}');
-    const lastSubchunk = subchunks.pop() as string;
-    for (const subchunk of subchunks) {
-      rightBracketCount += 1;
-      leftBracketCount += subchunk.split('{').length - 1;
-      response += `${subchunk}}`;
-      logger?.info('toParse:', response);
-      try {
-        const result = JSON.parse(response);
-        logger?.info('parsed:', result);
-        return result;
-      } catch (cause) {
-        // XXX There are other ways to detect an irrecoverable state.
-        // This is the simplest.
-        if (leftBracketCount === rightBracketCount) {
-          throw new SampleGenerationError(
-            response,
-            cause instanceof Error
-              ? cause
-              : new Error('Invalid JSON', { cause }),
-          );
-        }
+    response += delta;
+    logger?.info('toParse:', response);
+
+    try {
+      const result = parse(response, 0);
+      logger?.info('parsed:', result);
+      return result;
+    } catch (error) {
+      if (error instanceof PartialJSON) {
+        // Buffer is incomplete but structurally valid.
+      } else if (error instanceof MalformedJSON) {
+        throw new SampleGenerationError(response, error);
+      } else {
+        throw error;
       }
     }
-    leftBracketCount += lastSubchunk.split('{').length - 1;
-    response += lastSubchunk;
+
     if (maxChunkCount && chunkCount > maxChunkCount) {
       throw new SampleGenerationError(
         response,

yarn.lock

@@ -3674,6 +3674,7 @@ __metadata:
     eslint-plugin-n: "npm:^17.17.0"
     eslint-plugin-prettier: "npm:^5.2.6"
     eslint-plugin-promise: "npm:^7.2.1"
+    partial-json: "npm:^0.1.7"
     prettier: "npm:^3.5.3"
     rimraf: "npm:^6.0.1"
     ses: "npm:^1.14.0"
@@ -12398,6 +12399,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"partial-json@npm:^0.1.7":
+  version: 0.1.7
+  resolution: "partial-json@npm:0.1.7"
+  checksum: 10/6fb8d305638e4747fccfc0649b8a8de99314bfafcc4e3136a3a27c0632857c40b62e6e6bb5f17af00472387393f1d8a58a7865242ca20382af31b593a7bb1f89
+  languageName: node
+  linkType: hard
+
 "path-browserify@npm:^1.0.1":
   version: 1.0.1
   resolution: "path-browserify@npm:1.0.1"