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.2

Permissions in 0.2.2

  • Control chats chats.controlHighCreates chats, sends prompts and cancels runs.Send prompts, answer agent questions, and create, change, fork, revert, stop and group chats
  • Run other plugins' commands commands.runHighRuns commands of other plugins.Run the sidebar's New chat command from the title bar
  • Read chats chats.readMediumReads your transcripts and chat lists.Show workspaces, tasks, chats and transcripts, and follow them as agents work
  • Read files fs.readMediumReads files in the listed places.Suggest workspace files for @ mentionsPlaces: the open workspace
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Draw the chat grid, the title bar, and the Session panel with its rail buttonSlots: centertitlerailright

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

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=2 <4174.6 KB5 permissionsListed
0.2.4Oct 25, 2026>=2 <4174.2 KB5 permissionsListed
0.2.3Oct 24, 2026>=2 <4165.4 KB5 permissionsListed
0.2.2Oct 23, 2026>=2 <4165 KB5 permissionsListed
0.2.1Oct 6, 2026>=2 <3111.8 KB5 permissionsListed
0.2.0Oct 5, 2026>=2 <3105.1 KB5 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.