@4fu/arbor-plugin-http 0.0.0-stage → 2026.1106.0

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@4fu/arbor-plugin-http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.1106.0",
+  "type": "module",
+  "description": "The HTTP test channel plugin: a webhook in, sends out, and a page that drives the whole host.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "channel.d.ts",
+    "channel.js",
+    "index.d.ts",
+    "index.js",
+    "plugin.d.ts",
+    "plugin.js",
+    "server.d.ts",
+    "server.js",
+    "web/app.js",
+    "web/index.html"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/plugin-http"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "2026.1106.0",
+    "@4fu/arbor-interfaces": "2026.1106.0",
+    "@4fu/arbor-prompt": "2026.1106.0"
+  }
+}

package/plugin.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The HTTP test channel plugin: the whole domain, through the public plugin
+ * surface (docs/architecture.md#plugins).
+ *
+ * A plugin adds; it never patches the core. This one is a chat channel, and
+ * every part of it is optional in the framework's own terms:
+ *
+ * - **adapters**: the `Channel` (docs/journal.md#external-ids) and the
+ *   `EffectExecutor` that carries a window's `send` out through it
+ *   (docs/coordination.md#effects). The host takes the channel's push source and
+ *   ingests what arrives (docs/dispatch.md#tasks).
+ * - **a prompt section**: the blocks its own inputs use, so the model reads what
+ *   the channel is and how to answer on it. The blocks carry data; the words come
+ *   from the text table the section merges into the host's one renderer.
+ * - **judge criteria**: one extra criterion for its own inputs, which the host
+ *   collects for the judge (`Arbor.judgeCriteria`).
+ *
+ * What it deliberately does not have: a direct tool or a code mode module of its
+ * own. Capabilities are MCP servers and skills in `/env`, which the model reads,
+ * changes and reinstalls with `reload` like any item.
+ */
+import type { Effect, EffectExecutor, EffectResult, Plugin } from "@4fu/arbor-interfaces";
+import type { HttpChannel } from "./channel.ts";
+/** What the plugin is built from. */
+export interface HttpPluginOptions {
+    channel: HttpChannel;
+}
+/**
+ * The executor that carries a window's send out through the channel. One effect
+ * queue per host executes each effect exactly once and in the order it was made
+ * (docs/coordination.md#effects); this is the executor that owns the sends whose
+ * target is one of this channel's conversations.
+ */
+export declare class HttpSendExecutor implements EffectExecutor {
+    readonly id = "http-send";
+    private readonly channel;
+    constructor(channel: HttpChannel);
+    can(effect: Effect): boolean;
+    run(effect: Effect): Promise<EffectResult>;
+}
+/** The plugin a deployment registers with the host. */
+export declare function httpPlugin(options: HttpPluginOptions): Plugin;

package/plugin.js

@@ -0,0 +1,95 @@
+/**
+ * The HTTP test channel plugin: the whole domain, through the public plugin
+ * surface (docs/architecture.md#plugins).
+ *
+ * A plugin adds; it never patches the core. This one is a chat channel, and
+ * every part of it is optional in the framework's own terms:
+ *
+ * - **adapters**: the `Channel` (docs/journal.md#external-ids) and the
+ *   `EffectExecutor` that carries a window's `send` out through it
+ *   (docs/coordination.md#effects). The host takes the channel's push source and
+ *   ingests what arrives (docs/dispatch.md#tasks).
+ * - **a prompt section**: the blocks its own inputs use, so the model reads what
+ *   the channel is and how to answer on it. The blocks carry data; the words come
+ *   from the text table the section merges into the host's one renderer.
+ * - **judge criteria**: one extra criterion for its own inputs, which the host
+ *   collects for the judge (`Arbor.judgeCriteria`).
+ *
+ * What it deliberately does not have: a direct tool or a code mode module of its
+ * own. Capabilities are MCP servers and skills in `/env`, which the model reads,
+ * changes and reinstalls with `reload` like any item.
+ */
+/** The block kind this plugin's prompt section renders. */
+const HTTP_BLOCKS = [
+    {
+        kind: "http_channel",
+        fields: [
+            { name: "channel", type: "string", required: true },
+            { name: "conversations", type: "strings" },
+        ],
+        lines: ["http.channel", "http.conversations"],
+    },
+];
+/** The fixed strings its own block writes, merged into the host's table. */
+const HTTP_TEXT = {
+    "http.channel": "HTTP 测试频道 {channel}：回复用 send，目标写 {channel}:<来源名>。",
+    "http.conversations": "当前来源：{conversations}",
+};
+/**
+ * The executor that carries a window's send out through the channel. One effect
+ * queue per host executes each effect exactly once and in the order it was made
+ * (docs/coordination.md#effects); this is the executor that owns the sends whose
+ * target is one of this channel's conversations.
+ */
+export class HttpSendExecutor {
+    id = "http-send";
+    channel;
+    constructor(channel) {
+        this.channel = channel;
+    }
+    can(effect) {
+        return effect.kind === "send" && effect.target.startsWith(`${this.channel.id}:`);
+    }
+    async run(effect) {
+        const sent = await this.channel.send({
+            channel: this.channel.id,
+            target: effect.target,
+            content: effect.content,
+            ...(effect.replyTo === undefined ? {} : { replyTo: effect.replyTo }),
+        });
+        // The native id the outside world gave it, which the host records on the
+        // effect's result, so a ref resolves to what was sent.
+        return { ok: true, external: sent.external };
+    }
+}
+/** The plugin a deployment registers with the host. */
+export function httpPlugin(options) {
+    const channel = options.channel;
+    return {
+        name: "http",
+        adapters: {
+            channels: [channel],
+            effectExecutors: [new HttpSendExecutor(channel)],
+        },
+        promptSection: {
+            tag: "http",
+            blocks: HTTP_BLOCKS,
+            text: HTTP_TEXT,
+            content: () => [
+                {
+                    kind: "http_channel",
+                    fields: {
+                        channel: channel.id,
+                        conversations: channel.conversations().map((target) => target.startsWith(`${channel.id}:`) ? target.slice(channel.id.length + 1) : target),
+                    },
+                },
+            ],
+        },
+        judgeCriteria: [
+            {
+                decision: "route",
+                criteria: ["一个来源里的消息进入已经在该来源中的窗口，而不是新开一个窗口"],
+            },
+        ],
+    };
+}

package/server.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The runnable entry point: compose the default stack around the HTTP test
+ * channel and start the server.
+ *
+ * ```sh
+ * DEEPSEEK_API_KEY=… JEV_API_KEY=… pnpm --filter @4fu/arbor-plugin-http start
+ * ```
+ *
+ * Every module is the default one - the SQLite journal and notes, Jev, the
+ * directory environment, the workspace `openWorkspace` picks, pi as the backend
+ * (docs/architecture.md#stack) - and the one plugin is the HTTP channel. Nothing
+ * here is specific to this plugin: a deployment that plugs a different channel in
+ * composes the same stack the same way.
+ *
+ * Configuration names a secret and never holds its value
+ * (docs/architecture.md#data-placement). The keys pi and Jev read are
+ * environment variables those two modules read themselves; the settings name
+ * them, so the host's scrub covers every string that leaves it.
+ *
+ * | Name | What it names | Default |
+ * | --- | --- | --- |
+ * | `ARBOR_DATA_DIR` | where the journal, notes, `/env` and the workspaces live | `./.arbor/http` |
+ * | `ARBOR_HOST` | the host the page binds | `127.0.0.1` |
+ * | `ARBOR_PORT` | the port the page binds | `8787` |
+ * | `ARBOR_MODEL` | the model the `chat` tier maps to | `deepseek-flash` |
+ * | `DEEPSEEK_API_KEY` | pi's key for DeepSeek | - |
+ * | `JEV_API_KEY` | Jev's key | - |
+ *
+ * The page is a local test tool: it binds localhost by default, and visibility,
+ * permissions and auth are deferred.
+ */
+export {};

package/server.js

@@ -0,0 +1,121 @@
+/**
+ * The runnable entry point: compose the default stack around the HTTP test
+ * channel and start the server.
+ *
+ * ```sh
+ * DEEPSEEK_API_KEY=… JEV_API_KEY=… pnpm --filter @4fu/arbor-plugin-http start
+ * ```
+ *
+ * Every module is the default one - the SQLite journal and notes, Jev, the
+ * directory environment, the workspace `openWorkspace` picks, pi as the backend
+ * (docs/architecture.md#stack) - and the one plugin is the HTTP channel. Nothing
+ * here is specific to this plugin: a deployment that plugs a different channel in
+ * composes the same stack the same way.
+ *
+ * Configuration names a secret and never holds its value
+ * (docs/architecture.md#data-placement). The keys pi and Jev read are
+ * environment variables those two modules read themselves; the settings name
+ * them, so the host's scrub covers every string that leaves it.
+ *
+ * | Name | What it names | Default |
+ * | --- | --- | --- |
+ * | `ARBOR_DATA_DIR` | where the journal, notes, `/env` and the workspaces live | `./.arbor/http` |
+ * | `ARBOR_HOST` | the host the page binds | `127.0.0.1` |
+ * | `ARBOR_PORT` | the port the page binds | `8787` |
+ * | `ARBOR_MODEL` | the model the `chat` tier maps to | `deepseek-flash` |
+ * | `DEEPSEEK_API_KEY` | pi's key for DeepSeek | - |
+ * | `JEV_API_KEY` | Jev's key | - |
+ *
+ * The page is a local test tool: it binds localhost by default, and visibility,
+ * permissions and auth are deferred.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Arbor, openWorkspace } from "@4fu/arbor-core";
+import { DirectoryEnvironment } from "@4fu/arbor-environment-dir";
+import { SqliteJournal } from "@4fu/arbor-journal-sqlite";
+import { SqliteNoteStore } from "@4fu/arbor-notes-sqlite";
+import { ProcessSupervisor } from "@4fu/arbor-supervisor-process";
+import { PiAgentBackend } from "@4fu/arbor-agent-pi";
+import { HttpChannel } from "./channel.js";
+import { httpPlugin } from "./plugin.js";
+/** The environment variables this entry point reads. None of them is a secret. */
+const DATA_DIR = process.env.ARBOR_DATA_DIR ?? join(tmpdir(), "arbor-http");
+const HOST = process.env.ARBOR_HOST ?? "127.0.0.1";
+const PORT = Number(process.env.ARBOR_PORT ?? 8787);
+const MODEL = process.env.ARBOR_MODEL ?? "deepseek-flash";
+/** The tier a new window runs at, and what that tier is for. */
+const TIER = "chat";
+/** The secrets this configuration names. Their values stay in the environment. */
+const SECRETS = ["DEEPSEEK_API_KEY", "JEV_API_KEY"];
+const SETTINGS = {
+    identity: "arbor 的 HTTP 测试频道接线员",
+    generalRules: ["用中文回答", "回答要短"],
+    modelTiers: { [TIER]: MODEL },
+    defaultTier: TIER,
+    judge: {
+        tierCriteria: {
+            [TIER]: "A short conversational message on the HTTP test channel, where a fast model is enough.",
+        },
+    },
+    window: { idleSeconds: 120 },
+    secrets: [...SECRETS],
+};
+async function main() {
+    await mkdir(DATA_DIR, { recursive: true });
+    const journal = new SqliteJournal({ path: join(DATA_DIR, "journal.sqlite") });
+    const notes = new SqliteNoteStore({ path: join(DATA_DIR, "notes.sqlite"), journal });
+    const supervisor = new ProcessSupervisor({ root: join(DATA_DIR, "services") });
+    const environment = new DirectoryEnvironment({
+        root: join(DATA_DIR, "env"),
+        supervisor,
+        // A service's secret is read from the environment by name, never held here.
+        secretOf: (name) => process.env[name],
+    });
+    // The settings are installed, so they live in `/env` where the model changes
+    // them with `reload`, and the host reads them back at every change.
+    const seed = join(DATA_DIR, "seed");
+    await mkdir(seed, { recursive: true });
+    const settingsPath = join(seed, "settings.json");
+    await writeFile(settingsPath, JSON.stringify(SETTINGS, null, 2), "utf8");
+    await environment.install([{ kind: "settings", name: "settings", path: settingsPath }]);
+    // The workspace: one directory per window, under the data directory. It needs
+    // nothing a host does not already have, so it runs on any platform.
+    const workspace = await openWorkspace({ root: join(DATA_DIR, "workspaces") });
+    // The channel is created before the host and reads the board from it, so the
+    // plugin holds no reference to the host and the deployment supplies one.
+    let arbor;
+    const channel = new HttpChannel({
+        host: HOST,
+        port: PORT,
+        board: () => arbor?.boardLines() ?? [],
+    });
+    arbor = new Arbor({
+        journal,
+        notes,
+        backend: new PiAgentBackend(),
+        workspace,
+        environment,
+        supervisor,
+        settings: SETTINGS,
+        // The judge is the default: Jev, which reads `JEV_API_KEY` per request. A
+        // host without one falls back on every decision's own rule.
+        plugins: [httpPlugin({ channel })],
+    });
+    await arbor.start();
+    const address = await channel.listen();
+    const models = await arbor.models();
+    console.log(`arbor: HTTP test channel on ${address}`);
+    console.log(`arbor: journal ${join(DATA_DIR, "journal.sqlite")}, model ${SETTINGS.modelTiers?.[TIER]}`);
+    console.log(`arbor: workspace ${join(DATA_DIR, "workspaces")}`);
+    console.log(`arbor: ${models.length} models in the catalog, ${arbor.channels().length} channel plugged in`);
+    console.log(`arbor: open ${address} in a browser, or POST a message to ${address}/webhook`);
+    const stop = async () => {
+        await channel.close();
+        await arbor?.close();
+    };
+    process.on("SIGINT", () => void stop().then(() => process.exit(0)));
+    process.on("SIGTERM", () => void stop().then(() => process.exit(0)));
+}
+await main();

package/web/app.js

@@ -0,0 +1,197 @@
+/**
+ * The page the HTTP test channel serves: pick or create a conversation, send a
+ * message, watch replies arrive, and read the board.
+ *
+ * Plain JavaScript, no build step. Every string that came from outside is set
+ * with `textContent`, so message text can never become markup. The page polls,
+ * because a test tool does not need a socket.
+ */
+
+"use strict";
+
+const POLL_MS = 1200;
+
+/** What the page holds between polls. */
+const state = {
+  channel: "http",
+  online: false,
+  address: "",
+  conversations: [],
+  board: [],
+  messages: [],
+  selected: null,
+  /** Conversations the page made that the channel has no message for yet. */
+  created: [],
+};
+
+const elements = {
+  status: document.getElementById("status"),
+  conversationList: document.getElementById("conversation-list"),
+  newConversation: document.getElementById("new-conversation"),
+  newConversationName: document.getElementById("new-conversation-name"),
+  conversationTitle: document.getElementById("conversation-title"),
+  messages: document.getElementById("messages"),
+  chatEmpty: document.getElementById("chat-empty"),
+  composer: document.getElementById("composer"),
+  text: document.getElementById("text"),
+  send: document.getElementById("send"),
+  boardBody: document.getElementById("board-body"),
+  boardEmpty: document.getElementById("board-empty"),
+};
+
+/** One GET against the channel's own reads. */
+async function get(path) {
+  const response = await fetch(path, { headers: { accept: "application/json" } });
+  return response.json();
+}
+
+/** The conversation name without the channel prefix, for display. */
+function nameOf(target) {
+  const prefix = `${state.channel}:`;
+  return target.startsWith(prefix) ? target.slice(prefix.length) : target;
+}
+
+function renderStatus() {
+  elements.status.textContent = state.online
+    ? `${state.channel} 在线 · ${state.address}`
+    : `${state.channel} 离线`;
+}
+
+function renderConversations() {
+  const known = new Set(state.conversations.map((one) => one.target));
+  const every = [...state.conversations, ...state.created.filter((target) => !known.has(target)).map((target) => ({ target, messages: 0 }))];
+  elements.conversationList.replaceChildren(
+    ...every.map((one) => {
+      const item = document.createElement("li");
+      item.setAttribute("role", "button");
+      item.setAttribute("aria-current", String(one.target === state.selected));
+      const label = document.createElement("span");
+      label.textContent = nameOf(one.target);
+      const count = document.createElement("span");
+      count.className = "count";
+      count.textContent = String(one.messages);
+      item.append(label, count);
+      item.addEventListener("click", () => {
+        state.selected = one.target;
+        void refreshMessages();
+      });
+      return item;
+    }),
+  );
+}
+
+function renderMessages() {
+  const title = state.selected === null ? "选择一个来源" : `来源 ${nameOf(state.selected)}`;
+  elements.conversationTitle.textContent = title;
+  const shown = state.selected === null ? [] : state.messages.filter((one) => one.conversation === state.selected);
+  elements.chatEmpty.hidden = shown.length > 0;
+  elements.messages.replaceChildren(
+    ...shown.map((message) => {
+      const item = document.createElement("li");
+      item.className = `message ${message.direction}`;
+      const head = document.createElement("header");
+      const who = document.createElement("span");
+      who.textContent = message.direction === "out" ? "arbor" : message.from;
+      const when = document.createElement("time");
+      when.textContent = new Date(message.time).toLocaleTimeString();
+      head.append(who, when);
+      const body = document.createElement("div");
+      body.textContent = message.text;
+      item.append(head, body);
+      return item;
+    }),
+  );
+}
+
+function renderBoard() {
+  elements.boardEmpty.hidden = state.board.length > 0;
+  elements.boardBody.replaceChildren(
+    ...state.board.map((line) => {
+      const row = document.createElement("tr");
+      const cells = [
+        line.window,
+        line.state,
+        line.doing,
+        `${line.usage.used}/${line.usage.limit}`,
+      ];
+      for (const [index, value] of cells.entries()) {
+        const cell = document.createElement("td");
+        if (index === 2) cell.className = "doing";
+        cell.textContent = value;
+        row.append(cell);
+      }
+      return row;
+    }),
+  );
+}
+
+/** One poll: the state, then the selected conversation's messages. */
+async function refresh() {
+  let next;
+  try {
+    next = await get("/api/state");
+  } catch {
+    state.online = false;
+    renderStatus();
+    return;
+  }
+  state.channel = next.channel;
+  state.online = next.online;
+  state.address = next.address;
+  state.conversations = next.conversations;
+  state.board = next.board;
+  // A conversation the page made stays selected until the channel has a message
+  // for it, so a new conversation does not disappear on the next poll.
+  if (state.selected === null && state.conversations.length > 0) {
+    state.selected = state.conversations[0].target;
+  }
+  renderStatus();
+  renderConversations();
+  renderBoard();
+  await refreshMessages();
+}
+
+async function refreshMessages() {
+  if (state.selected === null) {
+    state.messages = [];
+    renderMessages();
+    renderConversations();
+    return;
+  }
+  const page = await get(`/api/messages?conversation=${encodeURIComponent(state.selected)}`);
+  state.messages = page.items;
+  renderMessages();
+  renderConversations();
+}
+
+elements.newConversation.addEventListener("submit", (event) => {
+  event.preventDefault();
+  const name = elements.newConversationName.value.trim();
+  if (name === "") return;
+  const target = `${state.channel}:${name}`;
+  if (!state.created.includes(target)) state.created.push(target);
+  state.selected = target;
+  elements.newConversationName.value = "";
+  void refreshMessages();
+});
+
+elements.composer.addEventListener("submit", async (event) => {
+  event.preventDefault();
+  const text = elements.text.value.trim();
+  if (text === "" || state.selected === null) return;
+  elements.send.disabled = true;
+  try {
+    await fetch("/webhook", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ conversation: nameOf(state.selected), text }),
+    });
+    elements.text.value = "";
+    await refresh();
+  } finally {
+    elements.send.disabled = false;
+  }
+});
+
+void refresh();
+setInterval(() => void refresh(), POLL_MS);