Official
chat
Built-in chat UI (JavaScript UI plugin).
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install convergence/chat@0.2.3
Permissions in 0.2.3
Files
context.test.ts14.3 KB
import assert from "node:assert/strict";
import test from "node:test";
import * as Effect from "effect/Effect";
import type { Api, ArchiveRecord } from "convergence";
import type { Params } from "convergence/services";
import { ChatContext } from "./context-contract.ts";
import { transcriptPolicy } from "./context-service.ts";
import {
continuation,
contextBudget,
contextFormat,
detailedTranscript,
estimatedTokens,
transcriptContext,
} from "./context.ts";
function record(id: string, item: Record<string, unknown>, position = 0): ArchiveRecord {
return { id, revisionId: `revision:${id}`, attachmentId: "source", agentId: "A", nativeItemId: null, position, item };
}
const artifact = {
id: "export",
path: "/workspace/.divergence/handoff-root/export.txt",
regenerateCommand: "cvg --data-dir '/data/dev' artifact regenerate --reference 'capability'",
};
test("complete JSONL preserves immutable inline documents and originating turn references", () => {
const saved = record(
"visual-record",
{
id: "saved-visual",
role: "artifact",
userItemId: "host-user",
artifact: {
owner: "visuals",
type: "visual",
version: 2,
title: "Balance",
summary: "Loss then gain",
data: { version: 2, panels: [{ id: "balance", values: [-7, 21] }] },
},
},
1,
);
const records = [
record("user-record", { id: "host-user", role: "user", blocks: [{ type: "text", text: "compare" }] }),
saved,
];
const lines = detailedTranscript(records)
.trimEnd()
.split("\n")
.map((line) => JSON.parse(line));
assert.equal(lines.length, 2);
assert.deepEqual(lines[1], { section: 2, ...saved });
assert.equal(lines[1].item.userItemId, lines[0].item.id);
});
test("UTF-8 estimate counts astral, multibyte and unpaired surrogates, rounding once", () => {
for (const value of ["", "a", "abcde", "é", "中", "🦄", "aé中🦄", "\ud800", "\udc00", "\ud800a"]) {
assert.equal(estimatedTokens(value), Math.ceil(Buffer.byteLength(value, "utf8") / 4), JSON.stringify(value));
}
});
test("detailed JSONL preserves every stored record, nested transcript and unknown field without putting payloads inline", () => {
const records = [
record("human", { role: "user", blocks: [{ type: "text", text: "old decision" }] }),
record("attempt", {
role: "tool",
call: {
name: "shell",
input: { command: "printf original" },
output: "RESULT_ONLY_IN_FILE\nsecond physical-looking line 🦄",
content: [{ type: "diff", diff: "DIFF_ONLY_IN_FILE" }],
status: "failed",
futureField: { preserved: true },
},
}),
record("reply", { role: "assistant", text: "The quoted RESULT_IN_MESSAGE stays." }),
record("thought", { role: "reasoning", text: "REASONING_ONLY_IN_FILE" }),
record("task", {
role: "task",
task: { id: "nested", title: "child" },
items: [
{ role: "reasoning", text: "NESTED_THOUGHT" },
{ role: "tool", call: { name: "read", input: "nested.ts", output: "NESTED_RESULT" } },
],
}),
record("notice", { role: "notice", text: "NOTICE_ONLY_IN_FILE" }),
record("compact", { role: "compaction", summary: "SUMMARY_ONLY_IN_FILE" }),
record("plan", { role: "plan", plan: { entries: [{ content: "PLAN_ONLY_IN_FILE" }] } }),
record("future", { role: "future-role", opaque: [1, { preserved: true }] }),
];
const result = transcriptContext(records, { artifact });
const lines = result.fullText
.trimEnd()
.split("\n")
.map((line) => JSON.parse(line));
assert.equal(lines.length, records.length, "embedded newlines must not break JSONL line references");
assert.deepEqual(
lines.map(({ section: _, ...stored }) => stored),
records,
);
assert.deepEqual(
result.exportedRecords,
records.map((r) => r.id),
);
assert.deepEqual(result.inlineRecords, ["human", "attempt", "reply"]);
assert.equal(result.overflow, false);
for (const excluded of [
"printf original",
"RESULT_ONLY_IN_FILE",
"DIFF_ONLY_IN_FILE",
"REASONING_ONLY_IN_FILE",
"NESTED_RESULT",
"NOTICE_ONLY_IN_FILE",
"SUMMARY_ONLY_IN_FILE",
"PLAN_ONLY_IN_FILE",
"revision:attempt",
]) {
assert.ok(!result.text.includes(excluded), excluded);
}
assert.match(result.text, /Tools \("A"\): "shell"\. Details: section 2, lines 2-2/);
assert.match(result.text, /RESULT_IN_MESSAGE/);
assert.match(result.text, /schema example/);
assert.match(result.text, /jq -c 'select\(\.section == 2\) \| \.item.call'/);
assert.equal(result.estimatedTokens, Math.ceil(Buffer.byteLength(`${continuation}\n${result.text}`, "utf8") / 4));
});
test("consecutive tool blocks count names and reference exact full-file sections across source changes", () => {
const tool = (id: string, name: string) => record(id, { role: "tool", call: { name, input: { id } } });
const records = [
record("u", { role: "user", blocks: [{ type: "text", text: "request" }] }),
tool("one", "Read"),
tool("two", "Bash"),
tool("three", "Read"),
record("a", { role: "assistant", text: "reply" }),
record("r", { role: "reasoning", text: "hidden" }),
tool("four", "Search"),
{ ...tool("five", "Read"), agentId: "B" },
{ ...tool("six", "Read"), agentId: "B", attachmentId: "another-session" },
];
const result = transcriptContext(records, { artifact });
assert.match(result.text, /"Read" ×2, "Bash"\. Details: section 2, lines 2-4/);
assert.match(result.text, /"Search"\. Details: section 5, lines 7-7/);
assert.match(result.text, /Tools \("B"\): "Read"\. Details: section 6, lines 8-8/);
assert.match(result.text, /"Read"\. Details: section 7, lines 9-9/);
const lines = result.fullText
.trimEnd()
.split("\n")
.map((line) => JSON.parse(line));
assert.deepEqual(
lines.map((line) => line.section),
[1, 2, 2, 2, 3, 4, 5, 6, 7],
);
assert.deepEqual(
lines.filter((line) => line.section === 2).map((line) => line.item.call.input.id),
["one", "two", "three"],
);
});
test("large tool inputs, results and reasoning do not consume the inline allowance", () => {
const small = [
record("t", { role: "tool", call: { name: "Read", input: "input", output: "output" } }),
record("r", { role: "reasoning", text: "thought" }),
record("a", { role: "assistant", text: "latest answer" }),
];
const large = [
record("t", { role: "tool", call: { name: "Read", input: "i".repeat(100_000), output: "o".repeat(200_000) } }),
record("r", { role: "reasoning", text: "r".repeat(100_000) }),
small[2],
];
const compact = transcriptContext(small, { artifact });
const result = transcriptContext(large, { artifact });
assert.equal(result.text, compact.text);
assert.equal(result.estimatedTokens, compact.estimatedTokens);
assert.equal(result.overflow, false);
assert.ok(estimatedTokens(result.fullText) > contextBudget);
});
test("return catch-up uses missing records inline but stable references into the entire detailed chat", () => {
const all = [
record("old", { role: "user", blocks: [{ type: "text", text: "ALREADY_COVERED" }] }),
record("old-tool", { role: "tool", call: { name: "Read", output: "old output" } }),
record("new-tool", { role: "tool", call: { name: "Bash", input: "new input" } }),
record("new", { role: "assistant", text: "NEW_REPLY" }),
];
const result = transcriptContext(all.slice(2), { artifact, detailedRecords: all });
assert.deepEqual(result.exportedRecords, ["new-tool", "new"]);
assert.deepEqual(result.inlineRecords, ["new-tool", "new"]);
assert.ok(!result.text.includes("ALREADY_COVERED"));
assert.match(result.text, /"Bash"\. Details: section 2, lines 2-3/);
assert.match(result.fullText, /ALREADY_COVERED/);
assert.equal(result.fullText, detailedTranscript(all));
});
test("nontext user blocks remain complete in the file and honestly labelled inline", () => {
const blocks = [
{ type: "image", mimeType: "image/png", data: "BASE64_IMAGE" },
{ type: "audio", mimeType: "audio/wav", data: "BASE64_AUDIO" },
{ type: "file_ref", path: "old.ts" },
{ type: "resource", path: "carried.ts", text: "actual carried contents" },
{ type: "skill", name: "inspect", input: "skill argument" },
];
const result = transcriptContext([record("u", { role: "user", blocks })], { artifact });
assert.deepEqual(JSON.parse(result.fullText).item.blocks, blocks);
assert.match(result.text, /actual carried contents/);
assert.match(result.text, /skill argument/);
assert.match(result.text, /current availability is not guaranteed/);
assert.ok(!result.text.includes("BASE64"));
});
test("overflow file contains the whole exported portion while inline is the newest contiguous suffix", () => {
const records = [
record("old", { role: "assistant", text: "OLD_ONLY_FACT " + "o".repeat(97_000) }),
record("middle", { role: "user", blocks: [{ type: "text", text: "m".repeat(500) }] }),
record("new", { role: "assistant", text: "LATEST_FACT" }),
];
const result = transcriptContext(records, { artifact });
assert.equal(result.overflow, true);
assert.deepEqual(result.inlineRecords, ["middle", "new"]);
assert.ok(!result.text.includes("OLD_ONLY_FACT"));
assert.match(result.text, /LATEST_FACT/);
assert.match(result.fullText, /OLD_ONLY_FACT/);
assert.match(result.fullText, /LATEST_FACT/);
assert.match(result.text, /including inline and omitted records/);
assert.ok(result.estimatedTokens <= contextBudget);
assert.deepEqual(transcriptContext(records, { artifact }), result, "same snapshot/configuration is deterministic");
});
test("an oversized newest record cannot be skipped to squeeze in older small records", () => {
const result = transcriptContext(
[
record("small-old", { role: "assistant", text: "SHOULD_NOT_BE_INLINE" }),
record("large-new", { role: "assistant", text: "N".repeat(97_000) }),
],
{ artifact },
);
assert.deepEqual(result.inlineRecords, []);
assert.ok(!result.text.includes("SHOULD_NOT_BE_INLINE"));
assert.match(result.fullText, /SHOULD_NOT_BE_INLINE/);
});
test("the exact budget boundary includes instructions, labels and guidance without truncation", () => {
const records = [record("one", { role: "assistant", text: "complete 🦄 message" + "x".repeat(1600) })];
const unrestricted = transcriptContext(records, { artifact });
const exact = unrestricted.estimatedTokens;
assert.equal(transcriptContext(records, { artifact, budget: exact }).overflow, false);
const overflow = transcriptContext(records, { artifact, budget: exact - 1 });
assert.equal(overflow.overflow, true);
assert.deepEqual(overflow.inlineRecords, []);
assert.equal(overflow.fullText, unrestricted.fullText);
assert.throws(() => transcriptContext(records, { budget: 1, artifact }), /too small/);
assert.ok(
transcriptContext([record("huge", { role: "assistant", text: "x".repeat(100_000) })], { artifact, budget: 100_000 })
.estimatedTokens <= contextBudget,
);
assert.throws(() => transcriptContext(records), /Detailed transcript requires/);
});
test("missing original tool arguments do not become rendered patch output", () => {
const result = transcriptContext(
[
record("legacy-edit", {
role: "tool",
call: {
name: "fileChange",
output: "PATCH_OUTPUT_SECRET",
content: [{ diff: "DIFF_SECRET" }],
},
}),
],
{ artifact },
);
const call = JSON.parse(result.fullText).item.call;
assert.ok(!Object.hasOwn(call, "input"));
assert.equal(call.output, "PATCH_OUTPUT_SECRET");
assert.deepEqual(call.content, [{ diff: "DIFF_SECRET" }]);
assert.ok(!result.text.includes("PATCH_OUTPUT_SECRET"));
assert.match(result.text, /absent fields were not recorded/);
});
test("stock policy materializes a full pinned file below budget and pages full history on return", async () => {
const all = Array.from({ length: 260 }, (_, index) =>
record(`r${index}`, { role: "assistant", text: `message ${index}` }, index),
);
const pages: number[] = [];
const configurations: Record<string, unknown>[] = [];
let enabled = true;
const api = {
settings: { get: () => enabled },
host: {
archive: {
records: async ({ offset, limit }: { offset: number; limit: number }) => {
pages.push(offset);
return { records: all.slice(offset, offset + limit) };
},
},
artifacts: {
create: async ({ configuration }: { configuration: Record<string, unknown> }) => {
configurations.push(configuration);
return artifact;
},
},
},
} as unknown as Api;
const policy = transcriptPolicy(api);
const params: Params<ChatContext, "prepare"> = {
snapshot: {
id: "pinned",
chatId: "chat",
lineageId: "lineage",
generation: 1,
createdAt: "2026-10-07T00:00:00Z",
records: all.length,
},
records: all.slice(-2),
configuration: {},
destination: { agentId: "A", capabilities: { labelled: true, ordinaryFiles: true, commands: true } },
};
const result = await Effect.runPromise(policy.prepare(params));
assert.deepEqual(pages, [0, 256]);
assert.deepEqual(result.covers, ["r258", "r259"]);
assert.equal(result.artifacts.length, 1);
assert.deepEqual(configurations[0], { format: contextFormat });
assert.ok(!result.text.includes("message 0\n"));
const rendered = await Effect.runPromise(
policy.render({ snapshot: params.snapshot, records: all, configuration: configurations[0] }),
);
assert.equal(rendered, detailedTranscript(all));
assert.equal(rendered.trimEnd().split("\n").length, 260);
pages.length = 0;
await Effect.runPromise(policy.prepare({ ...params, records: all }));
assert.deepEqual(pages, [], "full preparation already has the pinned archive");
await assert.rejects(
Effect.runPromise(
policy.prepare({
...params,
destination: { ...params.destination, capabilities: { labelled: true, ordinaryFiles: false, commands: false } },
}),
),
{ _tag: "ContextPreparationFailed", message: /ordinary workspace file access/ },
);
enabled = false;
await assert.rejects(Effect.runPromise(policy.prepare(params)), {
_tag: "ContextPreparationFailed",
message: /Built-in handoff is disabled/,
});
await assert.rejects(
Effect.runPromise(policy.render({ snapshot: params.snapshot, records: all, configuration: { format: "wrong" } })),
{ _tag: "ContextPreparationFailed", message: /pinned transcript format/ },
);
});Versions
| Version | Published | Plugin API | Size | Permissions | Status |
|---|---|---|---|---|---|
| 0.2.5latest | Nov 21, 2026 | >=2 <4 | 174.6 KB | 5 permissions | Listed |
| 0.2.4 | Oct 25, 2026 | >=2 <4 | 174.2 KB | 5 permissions | Listed |
| 0.2.3 | Oct 24, 2026 | >=2 <4 | 165.4 KB | 5 permissions | Listed |
| 0.2.2 | Oct 23, 2026 | >=2 <4 | 165 KB | 5 permissions | Listed |
| 0.2.1 | Oct 6, 2026 | >=2 <3 | 111.8 KB | 5 permissions | Listed |
| 0.2.0 | Oct 5, 2026 | >=2 <3 | 105.1 KB | 5 permissions | Listed |
No comments yet.