@frockbot/plugin-echo 0.0.0 → 0.1.0

package/frockbot.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 2,
+  "id": "echo",
+  "displayName": "Echo",
+  "version": "0.0.1",
+  "compatibility": {
+    "frockbot": ">=0.0.1"
+  },
+  "contributions": {
+    "runtime": {
+      "entry": "./agent"
+    }
+  },
+  "permissions": []
+}

package/package.json

@@ -1,14 +1,39 @@
 {
   "name": "@frockbot/plugin-echo",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts",
+    "./manifest": "./src/manifest.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./package.json": "./package.json"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-contracts": "0.1.0",
+    "@frockbot/plugin-models": "0.1.0",
+    "@frockbot/plugin-tools": "0.1.0",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@frockbot/plugin-testkit": "0.1.0",
+    "@types/bun": "1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-echo"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type LlmStreamEvent,
+  type NormalizedModelRequest,
+} from "@frockbot/kernel-contracts";
+import { LlmRegistry } from "@frockbot/plugin-models";
+import { ToolRegistry } from "@frockbot/plugin-tools";
+import {
+  createPluginHarness,
+  verifyPluginPackage,
+} from "@frockbot/plugin-testkit";
+import manifest from "../frockbot.json" with { type: "json" };
+import packageJson from "../package.json" with { type: "json" };
+import echoAgentPlugin, { ECHO_TOOL_NAME } from "./agent.js";
+
+function request(content: string): NormalizedModelRequest {
+  return {
+    requestId: "request",
+    provider: "fixture",
+    model: "fixture",
+    system: "",
+    messages: [{ role: "user", content }],
+    tools: [],
+  };
+}
+
+async function collect(
+  source: AsyncIterable<LlmStreamEvent>,
+): Promise<LlmStreamEvent[]> {
+  const events: LlmStreamEvent[] = [];
+  for await (const event of source) events.push(event);
+  return events;
+}
+
+describe("echo plugin", () => {
+  test("registers its tool and handles the reference echo command", async () => {
+    const harness = await createPluginHarness([LlmRegistry, ToolRegistry]);
+    harness.root.llm.register({
+      id: "fixture",
+      async *stream() {
+        yield* [] as LlmStreamEvent[];
+        throw new Error("echo middleware delegated unexpectedly");
+      },
+    });
+    const fiber = await harness.mount(echoAgentPlugin);
+    const controller = new AbortController();
+
+    const events = await collect(
+      harness.root.llm.stream(
+        request("/echo hello plugins"),
+        controller.signal,
+      ),
+    );
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({
+      type: "tool-call",
+      call: { name: ECHO_TOOL_NAME, input: { text: "hello plugins" } },
+    });
+    const first = events[0];
+    if (first?.type !== "tool-call") throw new Error("expected a tool call");
+    const preparation = await harness.root.tools.prepare(first.call, {
+      botId: "echo-bot",
+      agentId: "echo-agent",
+      compositionGenerationId: "bootstrap",
+      turnType: "chat" as const,
+      sessionId: "session",
+      effectId: "tool:1:1:0",
+      signal: controller.signal,
+    });
+    if (preparation.kind !== "ready") throw new Error("echo tool was denied");
+    expect(
+      await harness.root.tools.executePrepared(preparation, {
+        botId: "echo-bot",
+        agentId: "echo-agent",
+        compositionGenerationId: "bootstrap",
+        turnType: "chat" as const,
+        sessionId: "session",
+        effectId: "tool:1:1:0",
+        signal: controller.signal,
+      }),
+    ).toEqual({ content: "hello plugins", isError: false });
+
+    await fiber.dispose();
+    expect(harness.root.tools.schemas({ turnType: "chat" })).toEqual([]);
+    await harness.dispose();
+  });
+
+  test("satisfies plugin package conventions", () => {
+    expect(verifyPluginPackage({ packageJson, manifest })).toMatchObject({
+      name: "@frockbot/plugin-echo",
+      contributionKinds: ["runtime"],
+    });
+  });
+});

package/src/agent.ts

@@ -0,0 +1,78 @@
+import {
+  type LlmStreamEvent,
+  type NormalizedModelRequest,
+  type ToolDefinition,
+} from "@frockbot/kernel-contracts";
+import type { Plugin } from "cordis";
+
+export const ECHO_TOOL_NAME = "echo";
+
+interface EchoInput {
+  text: string;
+}
+
+function decodeEchoInput(input: unknown): EchoInput | undefined {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return undefined;
+  }
+  const text = (input as Record<string, unknown>).text;
+  if (typeof text !== "string" || !text.trim()) return undefined;
+  return { text: text.trim() };
+}
+
+export const echoTool: ToolDefinition = {
+  name: ECHO_TOOL_NAME,
+  description: "Return text to the conversation unchanged.",
+  inputSchema: {
+    type: "object",
+    properties: { text: { type: "string" } },
+    required: ["text"],
+    additionalProperties: false,
+  },
+  idempotent: true,
+  validate: (input: unknown) => decodeEchoInput(input) !== undefined,
+  execute: async (input: unknown) => {
+    const decoded = decodeEchoInput(input);
+    if (!decoded) return { content: "Echo text is required", isError: true };
+    return { content: decoded.text, isError: false };
+  },
+};
+
+function requestedEchoText(
+  request: NormalizedModelRequest,
+): string | undefined {
+  if (request.messages.at(-1)?.role === "tool") return undefined;
+  const user = request.messages.findLast((message) => message.role === "user");
+  if (user?.role !== "user") return undefined;
+  const match = /^\/echo(?:\s+([\s\S]+))?$/.exec(user.content.trim());
+  return match?.[1]?.trim() || undefined;
+}
+
+async function* requestEchoTool(
+  text: string,
+  signal: AbortSignal,
+): AsyncIterable<LlmStreamEvent> {
+  signal.throwIfAborted();
+  yield {
+    // pi-lens-ignore: ts:2322
+    type: "tool-call",
+    call: { id: crypto.randomUUID(), name: ECHO_TOOL_NAME, input: { text } },
+  };
+  yield {
+    type: "finish",
+    // pi-lens-ignore: ts:2322
+    reason: "tool-calls",
+  };
+}
+
+export const echoAgentPlugin: Plugin.Function = (ctx) => {
+  const unregisterTool = ctx.tools.register(echoTool);
+  const unregisterMiddleware = ctx.on("llm/stream", (request, signal, next) => {
+    const text = requestedEchoText(request);
+    return text ? requestEchoTool(text, signal) : next();
+  });
+  return [unregisterTool, unregisterMiddleware];
+};
+echoAgentPlugin.inject = ["tools", "llm"];
+
+export default echoAgentPlugin;

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./agent.js";
+export { default as echoManifest } from "./manifest.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-echo
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.