@jskit-ai/assistant-core 0.1.199 → 0.1.201

package/test/assistantBoundedToolLoop.test.js

@@ -0,0 +1,285 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createActionCatalogue } from "@jskit-ai/kernel/server/actions";
+import { createSchema } from "@jskit-ai/kernel/shared/validators";
+
+import { runBoundedAssistantToolLoop } from "../src/server/lib/assistantToolLoop.js";
+import { createServiceToolCatalog } from "../src/server/lib/serviceToolCatalog.js";
+import { parseConversationOutput, validateConversationOutputSchema } from "../src/server/conversation/structuredOutput.js";
+
+const policy = { maximumResponses: 4, timeoutMs: 90_000 };
+const outputSchema = { type: "object", additionalProperties: false, required: ["answer"],
+  properties: { answer: { type: "string", maxLength: 100 } } };
+const finalResponse = result => ({ ok: true, text: JSON.stringify({ response: { kind: "final", result } }) });
+const toolResponse = value => ({ ok: true, text: JSON.stringify({ response: {
+  kind: "tool", name: "bounded_read", arguments: { value: String(value) }
+} }) });
+
+function promptValue(prompt) {
+  const marker = "UNTRUSTED_APPLICATION_TOOL_RESULT_JSON_BEGIN\n";
+  if (!prompt.includes(marker)) return prompt.split("\n\n")[0];
+  return JSON.parse(prompt.split(marker)[1].split("\nUNTRUSTED_APPLICATION_TOOL_RESULT_JSON_END")[0]).result.prompt;
+}
+
+function boundedTools(execute) {
+  const actions = createActionCatalogue();
+  actions.register({ contributorId: "bounded.tools", domain: "bounded", actions: [{
+    id: "bounded.read", version: 1, kind: "query", channels: ["automation"], surfaces: ["app"],
+    permission: { require: "none" }, idempotency: "none",
+    input: { schema: createSchema({ value: { type: "string", enum: ["1", "2", "3", "4"], required: true } }), mode: "replace" },
+    output: { schema: createSchema({ prompt: { type: "string", required: true } }), mode: "replace" },
+    execute({ value }, context) { return execute({ value: Number(value) }, context); }
+  }] });
+  return createServiceToolCatalog(actions);
+}
+
+function responseOptions(options) {
+  assert.ok(options.outputSchema.properties.response.anyOf.length > 1);
+  assert.doesNotThrow(() => validateConversationOutputSchema(options.outputSchema, { maxOutputCharacters: 1000 }));
+  return { timeoutMs: options.timeoutMs };
+}
+
+test("bounded response policy accepts the fourth final response with the original per-response deadline", async () => {
+  const trace = [];
+  const responses = [{ step: 1 }, { step: 2 }, { step: 3 }, { answer: "Done" }];
+  let completed = 0;
+  const result = await runBoundedAssistantToolLoop({
+    prompt: "Initial request", outputSchema, toolContext: { surface: "app" },
+    toolCatalog: boundedTools(({ value }) => {
+      trace.push({ operation: value });
+      return { prompt: `Result ${value}` };
+    }),
+    policy,
+    limitError: new Error("Limit reached"),
+    async complete(prompt, options) {
+      trace.push({ prompt: promptValue(prompt), options: responseOptions(options) });
+      const response = responses[completed++];
+      return response.answer ? finalResponse(response) : toolResponse(response.step);
+    }
+  });
+  assert.deepEqual(result, responses[3]);
+  assert.equal(completed, 4);
+  assert.deepEqual(trace, [
+    { prompt: "Initial request", options: { timeoutMs: 90_000 } },
+    { operation: 1 },
+    { prompt: "Result 1", options: { timeoutMs: 90_000 } },
+    { operation: 2 },
+    { prompt: "Result 2", options: { timeoutMs: 90_000 } },
+    { operation: 3 },
+    { prompt: "Result 3", options: { timeoutMs: 90_000 } }
+  ]);
+});
+
+test("bounded response policy completes operation four before throwing the exact limit error without response five", async () => {
+  const trace = [];
+  const limitError = Object.assign(new Error("Original limit"), { code: "product_limit" });
+  let completed = 0;
+  await assert.rejects(runBoundedAssistantToolLoop({
+    prompt: "Initial request", outputSchema, toolContext: { surface: "app" },
+    toolCatalog: boundedTools(async ({ value }) => {
+      trace.push(`operation:${value}`);
+      await Promise.resolve();
+      trace.push(`prompt:${value}`);
+      return { prompt: `Result ${value}` };
+    }),
+    policy,
+    limitError,
+    async complete() {
+      trace.push(`response:${++completed}`);
+      return toolResponse(completed);
+    }
+  }), error => error === limitError);
+  assert.equal(completed, 4);
+  assert.deepEqual(trace, [
+    "response:1", "operation:1", "prompt:1",
+    "response:2", "operation:2", "prompt:2",
+    "response:3", "operation:3", "prompt:3",
+    "response:4", "operation:4", "prompt:4"
+  ]);
+});
+
+test("bounded response policy preserves the first response exception without action or recovery", async () => {
+  const failure = new Error("Original provider failure");
+  let completed = 0;
+  await assert.rejects(runBoundedAssistantToolLoop({
+    prompt: "Initial request", outputSchema, toolContext: { surface: "app" },
+    toolCatalog: boundedTools(() => assert.fail("A failed response must not execute an action")),
+    policy,
+    limitError: new Error("Limit reached"),
+    async complete() {
+      completed++;
+      throw failure;
+    }
+  }), error => error === failure);
+  assert.equal(completed, 1);
+});
+
+test("bounded response policy preserves action and result-prompt errors even on response four", async () => {
+  for (const failureRound of [1, 4]) {
+    const failure = new Error("Original action or result-bound failure");
+    let completed = 0;
+    let operations = 0;
+    await assert.rejects(runBoundedAssistantToolLoop({
+      prompt: "Initial request", outputSchema, toolContext: { surface: "app" },
+      toolCatalog: boundedTools(({ value }) => {
+        operations++;
+        if (value === failureRound) throw failure;
+        return { prompt: `Result ${value}` };
+      }),
+      policy,
+      limitError: new Error("Limit reached"),
+      async complete() { return toolResponse(++completed); }
+    }), error => error === failure);
+    assert.equal(completed, failureRound);
+    assert.equal(operations, failureRound);
+  }
+});
+
+test("bounded response policy checks abort before inference and after its identity capture before response policy", async () => {
+  const controller = new AbortController();
+  const reason = new Error("Cancelled");
+  const trace = [];
+  await assert.rejects(runBoundedAssistantToolLoop({
+    prompt: "Initial request", outputSchema, toolContext: { surface: "app" },
+    toolCatalog: boundedTools(() => assert.fail("Abort must precede response parsing or action execution")),
+    signal: controller.signal,
+    policy,
+    limitError: new Error("Limit reached"),
+    async complete() {
+      trace.push("native identity captured");
+      controller.abort(reason);
+      return { ok: false };
+    }
+  }), error => error === reason);
+  assert.deepEqual(trace, ["native identity captured"]);
+  await assert.rejects(runBoundedAssistantToolLoop({
+    prompt: "Initial request", outputSchema, toolContext: { surface: "app" },
+    toolCatalog: boundedTools(() => assert.fail("An aborted request must not execute an action")),
+    signal: controller.signal,
+    policy,
+    limitError: new Error("Limit reached"),
+    async complete() { assert.fail("An aborted request must not start inference"); }
+  }), error => error === reason);
+});
+
+test("bounded response policy retains the original action-abort versus exhaustion precedence", async () => {
+  for (const abortRound of [1, 4]) {
+    const controller = new AbortController();
+    const reason = new Error("Cancelled during action");
+    const limitError = new Error("Original limit");
+    let completed = 0;
+    await assert.rejects(runBoundedAssistantToolLoop({
+      prompt: "Initial request", outputSchema, toolContext: { surface: "app" },
+      toolCatalog: boundedTools(({ value }) => {
+        if (value === abortRound) controller.abort(reason);
+        return { prompt: `Result ${value}` };
+      }),
+      signal: controller.signal,
+      policy,
+      limitError,
+      async complete() { return toolResponse(++completed); }
+    }), error => error === (abortRound === 4 ? limitError : reason));
+    assert.equal(completed, abortRound);
+  }
+});
+
+test("bounded tools use the existing catalogue once per response and never execute for a final response", async () => {
+  const trace = [];
+  const actor = { id: "captured-actor" };
+  const catalog = boundedTools(async ({ value }, context) => {
+    assert.deepEqual(context.actor, actor);
+    assert.equal(context.channel, "automation");
+    trace.push(`operation:${value}`);
+    return { prompt: `Result ${value}` };
+  });
+  let toolSets = 0;
+  let completed = 0;
+  const result = await runBoundedAssistantToolLoop({ prompt: "Initial", outputSchema, policy, limitError: new Error("Limit"),
+    toolContext: { actor, surface: "app" },
+    toolCatalog: { ...catalog,
+      resolveToolSet(...args) { toolSets++; return catalog.resolveToolSet(...args); },
+      async executeToolCall(...args) {
+        const result = await catalog.executeToolCall(...args);
+        assert.equal(result.ok, true);
+        return result;
+      }
+    },
+    async complete(prompt, options) {
+      assert.deepEqual(responseOptions(options), { timeoutMs: 90_000 });
+      trace.push(`response:${++completed}:${promptValue(prompt)}`);
+      return completed === 4 ? finalResponse({ answer: "4" }) : toolResponse(completed);
+    }
+  });
+  assert.deepEqual(result, { answer: "4" });
+  assert.equal(toolSets, 4);
+  assert.deepEqual(trace, ["response:1:Initial", "operation:1", "response:2:Result 1", "operation:2",
+    "response:3:Result 2", "operation:3", "response:4:Result 3"]);
+});
+
+test("bounded tools preserve a fourth-operation host exception without another response", async () => {
+  const failure = Object.assign(new Error("Original query failure"), { statusCode: 503 });
+  let completed = 0;
+  let executions = 0;
+  const catalog = boundedTools(async ({ value }) => {
+    executions++;
+    if (value === 4) throw failure;
+    return { prompt: `Result ${value}` };
+  });
+  await assert.rejects(runBoundedAssistantToolLoop({ prompt: "Initial", outputSchema, policy, limitError: new Error("Limit"),
+    toolCatalog: catalog, toolContext: { surface: "app" },
+    async complete() { return toolResponse(++completed); }
+  }), error => error === failure);
+  assert.equal(completed, 4);
+  assert.equal(executions, 4);
+});
+
+test("bounded tools retain the original successful-operation abort versus exhaustion precedence", async () => {
+  for (const abortRound of [1, 4]) {
+    const controller = new AbortController();
+    const reason = new Error("Cancelled during operation");
+    const limitError = new Error("Original limit");
+    let completed = 0;
+    let executions = 0;
+    const catalog = boundedTools(async ({ value }) => {
+      executions++;
+      if (value === abortRound) controller.abort(reason);
+      return { prompt: `Result ${value}` };
+    });
+    await assert.rejects(runBoundedAssistantToolLoop({ prompt: "Initial", outputSchema, policy, signal: controller.signal, limitError,
+      toolCatalog: catalog, toolContext: { surface: "app" },
+      async complete() { return toolResponse(++completed); }
+    }), error => error === (abortRound === 4 ? limitError : reason));
+    assert.equal(completed, abortRound);
+    assert.equal(executions, abortRound);
+  }
+});
+
+test("bounded structured alternatives keep exact output bounds and reject open or ambiguous replies", () => {
+  const branch = (kind, maxLength) => ({ type: "object", additionalProperties: false, required: ["kind", "value"],
+    properties: { kind: { type: "string", enum: [kind] }, value: { type: "string", maxLength } } });
+  const schema = { type: "object", additionalProperties: false, required: ["response"],
+    properties: { response: { anyOf: [branch("first", 1), branch("second", 2)] } } };
+  const maximum = JSON.stringify({ response: { kind: "second", value: "\u0000\u0000" } }).length;
+  assert.doesNotThrow(() => validateConversationOutputSchema(schema, { maxOutputCharacters: maximum }));
+  assert.throws(() => validateConversationOutputSchema(schema, { maxOutputCharacters: maximum - 1 }),
+    /exceed the resolved output limit/u);
+  assert.deepEqual(parseConversationOutput('{"response":{"kind":"first","value":"x"}}', schema),
+    { response: { kind: "first", value: "x" } });
+  for (const value of [
+    { response: { kind: "first", value: "xx" } },
+    { response: { kind: "unknown", value: "x" } },
+    { response: { kind: "first", value: "x", result: "ambiguous" } }
+  ]) assert.throws(() => parseConversationOutput(JSON.stringify(value), schema), /invalid structured response/u);
+  const open = structuredClone(schema);
+  open.properties.response.anyOf[1].additionalProperties = true;
+  assert.throws(() => validateConversationOutputSchema(open, { maxOutputCharacters: maximum }), /reject additional properties/u);
+  const empty = structuredClone(schema);
+  empty.properties.response.anyOf = [];
+  assert.throws(() => validateConversationOutputSchema(empty, { maxOutputCharacters: maximum }), /closed object alternatives/u);
+  assert.throws(() => validateConversationOutputSchema(schema.properties.response, { maxOutputCharacters: maximum }),
+    /below its root/u);
+  let deep = schema;
+  for (let index = 0; index < 8; index++) deep = { type: "object", additionalProperties: false,
+    required: ["nested"], properties: { nested: deep } };
+  assert.throws(() => validateConversationOutputSchema(deep, { maxOutputCharacters: 16_000 }), /nested too deeply/u);
+});

package/test/assistantScroll.browser.test.js

@@ -270,6 +270,22 @@ test("conversation scrolling preserves history anchors and resets expansion on s
     await page.getByRole("button", { name: "Change conversation", exact: true }).click();
     await expect(page.getByRole("button", { name: "Show less", exact: true })).toHaveCount(0);
     await expect(page.getByRole("button", { name: "Read more", exact: true })).toBeAttached();
+    await expect(body).toBeVisible();
+    await expect(page.locator(".assistant-transcript__settling")).toHaveCount(0);
+    await page.evaluate(() => {
+      window.revealPlaceholders = 0;
+      new MutationObserver(records => {
+        for (const record of records) for (const node of record.addedNodes) {
+          if (node.nodeType === 1 && node.matches(".assistant-transcript__settling")) window.revealPlaceholders += 1;
+        }
+      }).observe(document.querySelector(".assistant-transcript"), { childList: true, subtree: true });
+    });
+    await page.getByRole("button", { name: "Toggle visibility", exact: true }).click();
+    await page.getByRole("button", { name: "Append reply", exact: true }).click();
+    await page.getByRole("button", { name: "Toggle visibility", exact: true }).click();
+    await expect(body).toBeVisible();
+    await expect.poll(() => body.evaluate(element => element.scrollHeight - element.scrollTop - element.clientHeight)).toBeLessThan(2);
+    assert.equal(await page.evaluate(() => window.revealPlaceholders), 0, "reopening loaded text does not flash a loading placeholder");
   } finally {
     await browser.close();
     await stopProcess(vite);

package/test/claudeClient.test.js

@@ -0,0 +1,189 @@
+import assert from "node:assert/strict";
+import { Readable, Duplex, PassThrough } from "node:stream";
+import { test } from "node:test";
+import { createClaudeJsonClient, readClaudeJsonFrames } from "../src/server/conversation/claudeClient.js";
+
+async function frames(chunks, options) {
+  const result = [];
+  for await (const frame of readClaudeJsonFrames(Readable.from(chunks), options)) result.push(frame);
+  return result;
+}
+
+test("Claude JSON frames survive every byte boundary, including Unicode and escaped newlines", async () => {
+  const expected = [{ type: "assistant", text: "Hello 🌏\n世界" }, { type: "result", is_error: false }];
+  const bytes = Buffer.from(`${expected.map((frame) => JSON.stringify(frame)).join("\r\n")}\n`);
+  assert.deepEqual(await frames([...bytes].map((byte) => Buffer.from([byte]))), expected);
+  assert.deepEqual(await frames([bytes]), expected);
+});
+
+test("Claude JSON framing bounds fragmented and complete frames and rejects malformed data without echoing it", async () => {
+  await assert.rejects(frames([Buffer.from('{"type":"secret"}\n')], { maxFrameBytes: 8 }), /size limit/u);
+  await assert.rejects(frames([Buffer.alloc(4, 32), Buffer.alloc(5, 32)], { maxFrameBytes: 8 }), /size limit/u);
+  await assert.rejects(frames([Buffer.from("secret token\n")]), (error) => !error.message.includes("secret token"));
+  await assert.rejects(frames([Buffer.from('{"type":"user","text":"'), Buffer.from([255]), Buffer.from('"}\n')]), /invalid UTF-8/u);
+  await assert.rejects(frames([Buffer.from('[]\n')]), /event type/u);
+  await assert.rejects(frames([Buffer.from('{"type":"result"}')]), /incomplete/u);
+  assert.deepEqual(await frames([Buffer.from('{"type":"result"}')], { allowIncompleteTail: true }), []);
+});
+
+function fakeStream(onWrite) {
+  return new Duplex({ read() {}, write(chunk, _encoding, callback) {
+    Promise.resolve().then(() => onWrite(JSON.parse(String(chunk)), this)).then(() => callback(), callback);
+  } });
+}
+
+test("Claude controls correlate out-of-order replies and events apply backpressure", async () => {
+  const requests = [];
+  const observed = [];
+  const stream = fakeStream((frame, socket) => {
+    requests.push(frame);
+    if (requests.length === 2) for (const request of [...requests].reverse()) {
+      socket.push(`${JSON.stringify({ type: "control_response", response: { subtype: "success", request_id: request.request_id, response: { name: request.request.subtype } } })}\n`);
+    }
+  });
+  const client = createClaudeJsonClient({ stream, onEvent: async (frame) => {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    observed.push(frame.number);
+  } });
+  assert.deepEqual(await Promise.all([client.request({ subtype: "one" }), client.request({ subtype: "two" })]), [{ name: "one" }, { name: "two" }]);
+  stream.push('{"type":"test","number":1}\n{"type":"test","number":2}\n');
+  stream.push(null);
+  await client.completion;
+  assert.deepEqual(observed, [1, 2]);
+  client.close();
+});
+
+test("Claude control replies bypass slow event persistence while events remain ordered", async () => {
+  const entered = Promise.withResolvers();
+  const release = Promise.withResolvers();
+  const observed = [];
+  const stream = fakeStream((frame, socket) => socket.push(`${JSON.stringify({
+    type: "control_response", response: { subtype: "success", request_id: frame.request_id, response: {} }
+  })}\n`));
+  const client = createClaudeJsonClient({ stream, onEvent: async (frame) => {
+    if (frame.number === 1) { entered.resolve(); await release.promise; }
+    observed.push(frame.number);
+  } });
+  stream.push('{"type":"event","number":1}\n{"type":"event","number":2}\n');
+  await entered.promise;
+  try {
+    await client.request({ subtype: "interrupt" }, { timeoutMs: 100 });
+    assert.deepEqual(observed, []);
+    release.resolve();
+    stream.push(null);
+    await client.completion;
+    assert.deepEqual(observed, [1, 2]);
+  } finally {
+    release.resolve();
+    client.close();
+  }
+});
+
+test("Claude interrupt uses the common 30-second control deadline", async (t) => {
+  t.mock.timers.enable({ apis: ["setTimeout"] });
+  const client = createClaudeJsonClient({ stream: fakeStream(() => {}) });
+  const pending = client.interrupt();
+  let settled = false;
+  const rejected = assert.rejects(pending, /interrupt timed out/u).then(() => { settled = true; });
+  t.mock.timers.tick(29_999);
+  await Promise.resolve();
+  assert.equal(settled, false);
+  t.mock.timers.tick(1);
+  await rejected;
+  client.close();
+  await client.completion;
+});
+
+test("Claude control timeouts and pipe closure reject pending work promptly", async () => {
+  const stream = fakeStream(() => {});
+  const client = createClaudeJsonClient({ stream, timeoutMs: 10 });
+  await assert.rejects(client.initialize(), /timed out/u);
+  const pending = client.request({ subtype: "interrupt" }, { timeoutMs: 10_000 });
+  stream.push(null);
+  await assert.rejects(pending, /ended unexpectedly/u);
+  await client.completion;
+});
+
+test("native startup ending before initialization reports failure without an unhandled stream error", async t => {
+  const writable = new PassThrough();
+  t.after(() => writable.destroy());
+  const stream = Duplex.from({ readable: Readable.from([]), writable });
+  const observed = [];
+  const client = createClaudeJsonClient({ stream, onFailure: error => observed.push(error) });
+  await assert.rejects(client.initialize(), /ended unexpectedly/u);
+  await client.completion;
+  await new Promise(resolve => setImmediate(resolve));
+  assert.equal(stream.destroyed, true);
+  assert.equal(observed.length, 1);
+  assert.equal(observed[0].code, "assistant_claude_observation_lost");
+});
+
+test("incoming tools wait for admission while outgoing interrupts remain responsive", async () => {
+  const admitted = Promise.withResolvers();
+  const invoked = Promise.withResolvers();
+  const finishTool = Promise.withResolvers();
+  const written = [];
+  const stream = fakeStream((frame, socket) => {
+    written.push(frame);
+    if (frame.type === "control_request") socket.push(`${JSON.stringify({ type: "control_response",
+      response: { subtype: "success", request_id: frame.request_id, response: {} } })}\n`);
+  });
+  const client = createClaudeJsonClient({ stream, onEvent: () => admitted.promise,
+    onControlRequest: async request => { invoked.resolve(request); return finishTool.promise; } });
+  stream.push('{"type":"user"}\n{"type":"control_request","request_id":"tool","request":{"subtype":"mcp_message"}}\n');
+  await client.interrupt();
+  assert.equal(written.filter(frame => frame.type === "control_response").length, 0);
+  admitted.resolve();
+  assert.equal((await invoked.promise).subtype, "mcp_message");
+  await client.interrupt();
+  finishTool.resolve({ mcp_response: { result: { content: [] } } });
+  await client.whenRequestsIdle();
+  assert.equal(written.find(frame => frame.response?.request_id === "tool").response.subtype, "success");
+  client.close();
+  await client.completion;
+});
+
+test("closing the native connection cancels incoming requests but drains invoked application work", async () => {
+  const invoked = Promise.withResolvers();
+  const finishTool = Promise.withResolvers();
+  const written = [];
+  const stream = fakeStream(frame => written.push(frame));
+  const client = createClaudeJsonClient({ stream, onControlRequest: async (_request, { signal }) => {
+    invoked.resolve(signal);
+    return finishTool.promise;
+  } });
+  stream.push('{"type":"control_request","request_id":"tool","request":{"subtype":"mcp_message"}}\n');
+  const signal = await invoked.promise;
+  client.close();
+  assert.equal(signal.aborted, true);
+  let drained = false;
+  const drain = client.whenRequestsIdle().then(() => { drained = true; });
+  await Promise.resolve();
+  assert.equal(drained, false);
+  finishTool.resolve({});
+  await drain;
+  await client.completion;
+  assert.equal(written.length, 0, "A cancelled control has no late response");
+});
+
+test("unregistered headless controls are denied and repeated active control IDs fail closed", async () => {
+  const response = Promise.withResolvers();
+  const stream = fakeStream(frame => response.resolve(frame));
+  const client = createClaudeJsonClient({ stream });
+  stream.push('{"type":"control_request","request_id":"permission","request":{"subtype":"can_use_tool"}}\n');
+  assert.equal((await response.promise).response.subtype, "error");
+  client.close();
+  await client.completion;
+
+  const failure = Promise.withResolvers();
+  const other = fakeStream(() => {});
+  const second = createClaudeJsonClient({ stream: other, onControlRequest: (_request, { signal }) => new Promise(resolve => {
+    signal.addEventListener("abort", resolve, { once: true });
+  }), onFailure: failure.resolve });
+  const duplicate = '{"type":"control_request","request_id":"same","request":{"subtype":"mcp_message"}}\n';
+  other.push(duplicate + duplicate);
+  assert.match((await failure.promise).message, /reused an active request/);
+  await second.whenRequestsIdle();
+  second.close();
+  await second.completion;
+});