fengming 0.3.9 → 0.3.11

package/docs/plan/ui-channels.md

@@ -1,284 +0,0 @@
----
-summary: Decouple semantic message presentation from channel native UI renderers.
-title: Channel presentation refactor plan
-read_when:
-  - Refactoring channel message UI, interactive payloads, or native channel renderers
-  - Changing message tool capabilities, delivery hints, or cross-context markers
-  - Debugging Discord Carbon import fanout or channel plugin runtime laziness
----
-
-## Status
-
-Implemented for the shared agent, CLI, plugin capability, and outbound delivery surfaces:
-
-- `ReplyPayload.presentation` carries semantic message UI.
-- `ReplyPayload.delivery.pin` carries sent-message pin requests.
-- Shared message actions expose `presentation`, `delivery`, and `pin` instead of provider-native `components`, `blocks`, `buttons`, or `card`.
-- Core renders or auto-degrades presentation through plugin-declared outbound capabilities.
-- Discord, Slack, Telegram, Mattermost, MS Teams, and Feishu renderers consume the generic contract.
-- Discord channel control-plane code no longer imports Carbon-backed UI containers.
-
-Canonical docs now live in [Message Presentation](/plugins/message-presentation).
-Keep this plan as historical implementation context; update the canonical guide
-for contract, renderer, or fallback behavior changes.
-
-## Problem
-
-Channel UI is currently split across several incompatible surfaces:
-
-- Core owns a Discord-shaped cross-context renderer hook through `buildCrossContextComponents`.
-- Discord `channel.ts` can import native Carbon UI through `DiscordUiContainer`, which pulls runtime UI dependencies into the channel plugin control plane.
-- The agent and CLI expose native payload escape hatches such as Discord `components`, Slack `blocks`, Telegram or Mattermost `buttons`, and Teams or Feishu `card`.
-- `ReplyPayload.channelData` carries both transport hints and native UI envelopes.
-- The generic `interactive` model exists, but it is narrower than the richer layouts already used by Discord, Slack, Teams, Feishu, LINE, Telegram, and Mattermost.
-
-This makes core aware of native UI shapes, weakens plugin runtime laziness, and gives agents too many provider-specific ways to express the same message intent.
-
-## Goals
-
-- Core decides the best semantic presentation for a message from declared capabilities.
-- Extensions declare capabilities and render semantic presentation into native transport payloads.
-- Web Control UI remains separate from chat native UI.
-- Native channel payloads are not exposed through the shared agent or CLI message surface.
-- Unsupported presentation features auto-degrade to the best text representation.
-- Delivery behavior such as pinning a sent message is generic delivery metadata, not presentation.
-
-## Non goals
-
-- No backwards compatibility shim for `buildCrossContextComponents`.
-- No public native escape hatches for `components`, `blocks`, `buttons`, or `card`.
-- No core imports of channel-native UI libraries.
-- No provider-specific SDK seams for bundled channels.
-
-## Target model
-
-Add a core-owned `presentation` field to `ReplyPayload`.
-
-```ts
-type MessagePresentationTone = "neutral" | "info" | "success" | "warning" | "danger";
-
-type MessagePresentation = {
-  tone?: MessagePresentationTone;
-  title?: string;
-  blocks: MessagePresentationBlock[];
-};
-
-type MessagePresentationBlock =
-  | { type: "text"; text: string }
-  | { type: "context"; text: string }
-  | { type: "divider" }
-  | { type: "buttons"; buttons: MessagePresentationButton[] }
-  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };
-
-type MessagePresentationButton = {
-  label: string;
-  value?: string;
-  url?: string;
-  style?: "primary" | "secondary" | "success" | "danger";
-};
-
-type MessagePresentationOption = {
-  label: string;
-  value: string;
-};
-```
-
-`interactive` becomes a subset of `presentation` during migration:
-
-- `interactive` text block maps to `presentation.blocks[].type = "text"`.
-- `interactive` buttons block maps to `presentation.blocks[].type = "buttons"`.
-- `interactive` select block maps to `presentation.blocks[].type = "select"`.
-
-The external agent and CLI schemas now use `presentation`; `interactive` remains an internal legacy parser/rendering helper for existing reply producers.
-The public producer-facing API treats `interactive` as deprecated. Runtime
-support remains so existing approval helpers and older plugins continue to
-work while new code emits `presentation`.
-
-## Delivery metadata
-
-Add a core-owned `delivery` field for send behavior that is not UI.
-
-```ts
-type ReplyPayloadDelivery = {
-  pin?:
-    | boolean
-    | {
-        enabled: boolean;
-        notify?: boolean;
-        required?: boolean;
-      };
-};
-```
-
-Semantics:
-
-- `delivery.pin = true` means pin the first successfully delivered message.
-- `notify` defaults to `false`.
-- `required` defaults to `false`; unsupported channels or failed pinning auto-degrade by continuing delivery.
-- Manual `pin`, `unpin`, and `list-pins` message actions remain for existing messages.
-
-Current Telegram ACP topic binding should move from `channelData.telegram.pin = true` to `delivery.pin = true`.
-
-## Runtime capability contract
-
-Add presentation and delivery render hooks to the runtime outbound adapter, not the control-plane channel plugin.
-
-```ts
-type ChannelPresentationCapabilities = {
-  supported: boolean;
-  buttons?: boolean;
-  selects?: boolean;
-  context?: boolean;
-  divider?: boolean;
-  tones?: MessagePresentationTone[];
-  limits?: {
-    actions?: {
-      maxActions?: number;
-      maxActionsPerRow?: number;
-      maxRows?: number;
-      maxLabelLength?: number;
-      maxValueBytes?: number;
-      supportsStyles?: boolean;
-      supportsDisabled?: boolean;
-      supportsLayoutHints?: boolean;
-    };
-    selects?: {
-      maxOptions?: number;
-      maxLabelLength?: number;
-      maxValueBytes?: number;
-    };
-    text?: {
-      maxLength?: number;
-      encoding?: "characters" | "utf8-bytes" | "utf16-units";
-      markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
-      supportsEdit?: boolean;
-    };
-  };
-};
-
-type ChannelDeliveryCapabilities = {
-  pinSentMessage?: boolean;
-};
-
-type ChannelOutboundAdapter = {
-  presentationCapabilities?: ChannelPresentationCapabilities;
-
-  renderPresentation?: (params: {
-    payload: ReplyPayload;
-    presentation: MessagePresentation;
-    ctx: ChannelOutboundSendContext;
-  }) => ReplyPayload | null;
-
-  deliveryCapabilities?: ChannelDeliveryCapabilities;
-
-  pinDeliveredMessage?: (params: {
-    cfg: FengMingConfig;
-    accountId?: string | null;
-    to: string;
-    threadId?: string | number | null;
-    messageId: string;
-    notify: boolean;
-  }) => Promise<void>;
-};
-```
-
-Core behavior:
-
-- Resolve target channel and runtime adapter.
-- Ask for presentation capabilities.
-- Degrade unsupported blocks and apply generic capability limits before
-  rendering.
-- Call `renderPresentation`.
-- If no renderer exists, convert presentation to text fallback.
-- After successful send, call `pinDeliveredMessage` when `delivery.pin` is requested and supported.
-
-## Channel mapping
-
-Discord:
-
-- Render `presentation` to components v2 and Carbon containers in runtime-only modules.
-- Keep accent color helpers in light modules.
-- Remove `DiscordUiContainer` imports from channel plugin control-plane code.
-
-Slack:
-
-- Render `presentation` to Block Kit.
-- Remove agent and CLI `blocks` input.
-
-Telegram:
-
-- Render text, context, and dividers as text.
-- Render actions and select as inline keyboards when configured and allowed for the target surface.
-- Use text fallback when inline buttons are disabled.
-- Move ACP topic pinning to `delivery.pin`.
-
-Mattermost:
-
-- Render actions as interactive buttons where configured.
-- Render other blocks as text fallback.
-
-MS Teams:
-
-- Render `presentation` to Adaptive Cards.
-- Keep manual pin/unpin/list-pins actions.
-- Optionally implement `pinDeliveredMessage` if Graph support is reliable for the target conversation.
-
-Feishu:
-
-- Render `presentation` to interactive cards.
-- Keep manual pin/unpin/list-pins actions.
-- Optionally implement `pinDeliveredMessage` for sent-message pinning if API behavior is reliable.
-
-LINE:
-
-- Render `presentation` to Flex or template messages where possible.
-- Fall back to text for unsupported blocks.
-- Remove LINE UI payloads from `channelData`.
-
-Plain or limited channels:
-
-- Convert presentation to text with conservative formatting.
-
-## Refactor steps
-
-1. Reapply the Discord release fix that splits `ui-colors.ts` from Carbon-backed UI and removes `DiscordUiContainer` from `extensions/discord/src/channel.ts`.
-2. Add `presentation` and `delivery` to `ReplyPayload`, outbound payload normalization, delivery summaries, and hook payloads.
-3. Add `MessagePresentation` schema and parser helpers in a narrow SDK/runtime subpath.
-4. Replace message capabilities `buttons`, `cards`, `components`, and `blocks` with semantic presentation capabilities.
-5. Add runtime outbound adapter hooks for presentation render and delivery pinning.
-6. Replace cross-context component construction with `buildCrossContextPresentation`.
-7. Delete `src/infra/outbound/channel-adapters.ts` and remove `buildCrossContextComponents` from channel plugin types.
-8. Change `maybeApplyCrossContextMarker` to attach `presentation` instead of native params.
-9. Update plugin-dispatch send paths to consume only semantic presentation and delivery metadata.
-10. Remove agent and CLI native payload params: `components`, `blocks`, `buttons`, and `card`.
-11. Remove SDK helpers that create native message-tool schemas, replacing them with presentation schema helpers.
-12. Remove UI/native envelopes from `channelData`; keep only transport metadata until each remaining field is reviewed.
-13. Migrate Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, and LINE renderers.
-14. Update docs for message CLI, channel pages, plugin SDK, and capability cookbook.
-15. Run import fanout profiling for Discord and affected channel entrypoints.
-
-Steps 1-11 and 13-14 are implemented in this refactor for the shared agent, CLI, plugin capability, and outbound adapter contracts. Step 12 remains a deeper internal cleanup pass for provider-private `channelData` transport envelopes. Step 15 remains follow-up validation if we want quantified import-fanout numbers beyond the type/test gate.
-
-## Tests
-
-Add or update:
-
-- Presentation normalization tests.
-- Presentation auto-degrade tests for unsupported blocks.
-- Cross-context marker tests for plugin dispatch and core delivery paths.
-- Channel render matrix tests for Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE, and text fallback.
-- Message tool schema tests proving native fields are gone.
-- CLI tests proving native flags are gone.
-- Discord entrypoint import-laziness regression covering Carbon.
-- Delivery pin tests covering Telegram and generic fallback.
-
-## Open questions
-
-- Should `delivery.pin` be implemented for Discord, Slack, MS Teams, and Feishu in the first pass, or only Telegram first?
-- Should `delivery` eventually absorb existing fields such as `replyToId`, `replyToCurrent`, `silent`, and `audioAsVoice`, or stay focused on post-send behaviors?
-- Should presentation support images or file references directly, or should media remain separate from UI layout for now?
-
-## Related
-
-- [Channels overview](/channels)
-- [Message presentation](/plugins/message-presentation)

package/docs/platforms/digitalocean.md

@@ -1,12 +0,0 @@
----
-summary: "Redirect to /install/digitalocean"
-title: "DigitalOcean (platform)"
-redirect: /install/digitalocean
----
-
-This page has moved to [DigitalOcean](/install/digitalocean).
-
-## Related
-
-- [Install overview](/install)
-- [VPS hosting](/vps)

package/docs/platforms/easyrunner.md

@@ -1,109 +0,0 @@
----
-summary: "Run the FengMing Gateway on EasyRunner with Podman and Caddy"
-read_when:
-  - Deploying FengMing on EasyRunner
-  - Running the Gateway behind EasyRunner's Caddy proxy
-  - Choosing persistent volumes and auth for a hosted Gateway
-title: "EasyRunner"
----
-
-EasyRunner can host the FengMing Gateway as a small containerized app behind its
-Caddy proxy. This guide assumes an EasyRunner host that runs Podman-compatible
-Compose apps and exposes HTTPS through Caddy.
-
-## Before you begin
-
-- An EasyRunner server with a domain routed to it.
-- A built or published FengMing container image.
-- A persistent config volume for `/home/node/.fengming`.
-- A persistent workspace volume for `/workspace`.
-- A strong Gateway token or password.
-
-Keep device auth enabled when possible. If your reverse proxy deployment cannot
-carry device identity correctly, fix trusted-proxy settings first; use
-dangerous auth bypasses only for a fully private, operator-controlled network.
-
-## Compose app
-
-Create an EasyRunner app with a Compose file shaped like this:
-
-```yaml
-services:
-  fengming:
-    image: ghcr.io/fengming/fengming:latest
-    restart: unless-stopped
-    environment:
-      FENGMING_GATEWAY_TOKEN: ${FENGMING_GATEWAY_TOKEN}
-      FENGMING_HOME: /home/node
-      FENGMING_STATE_DIR: /home/node/.fengming
-      FENGMING_CONFIG_PATH: /home/node/.fengming/fengming.json
-      FENGMING_WORKSPACE_DIR: /workspace
-    volumes:
-      - fengming-config:/home/node/.fengming
-      - fengming-workspace:/workspace
-    labels:
-      caddy: fengming.example.com
-      caddy.reverse_proxy: "{{upstreams 1455}}"
-    command: ["fengming", "gateway", "--bind", "lan", "--port", "1455"]
-
-volumes:
-  fengming-config:
-  fengming-workspace:
-```
-
-Replace `fengming.example.com` with your Gateway hostname. Store
-`FENGMING_GATEWAY_TOKEN` in EasyRunner's secret/environment manager instead of
-committing it to the app definition.
-
-## Configure FengMing
-
-Inside the persistent config volume, keep the Gateway reachable only through
-the proxy and require auth:
-
-```json5
-{
-  gateway: {
-    bind: "lan",
-    port: 1455,
-    auth: {
-      token: "${FENGMING_GATEWAY_TOKEN}",
-    },
-  },
-}
-```
-
-If Caddy terminates TLS for the Gateway, configure trusted proxy settings for
-the exact proxy path rather than disabling auth checks globally. See
-[Trusted proxy auth](/gateway/trusted-proxy-auth).
-
-## Verify
-
-From your workstation:
-
-```bash
-fengming gateway probe --url https://fengming.example.com --token <token>
-fengming gateway status --url https://fengming.example.com --token <token>
-```
-
-From the EasyRunner host, check the app logs for a listening Gateway and no
-startup SecretRef, plugin, or channel auth failures.
-
-## Updates and backups
-
-- Pull or build the new FengMing image, then redeploy the EasyRunner app.
-- Back up the `fengming-config` volume before updates.
-- Back up `fengming-workspace` if agents write durable project data there.
-- Run `fengming doctor` after major updates to catch config migrations and
-  service warnings.
-
-## Troubleshooting
-
-- `gateway probe` cannot connect: confirm the Caddy hostname points at the app
-  and that the container listens on `0.0.0.0:1455`.
-- Auth fails: rotate the token in EasyRunner secrets and the local client
-  command together.
-- Files are root-owned after restore: repair the mounted volumes so the
-  container user can write `/home/node/.fengming` and `/workspace`.
-- Browser or channel plugins fail: check whether the required external
-  binaries, network egress, and mounted credentials are available inside the
-  container.

package/docs/platforms/index.md

@@ -1,51 +0,0 @@
----
-summary: "Platform support overview (Gateway + companion apps)"
-read_when:
-  - Looking for OS support or install paths
-  - Deciding where to run the Gateway
-title: "Platforms"
----
-
-FengMing core is written in TypeScript. **Node is the recommended runtime**.
-Bun is not recommended for the Gateway — known issues with WhatsApp and
-Telegram channels; see [Bun (experimental)](/install/bun) for details.
-
-## Choose your OS
-
-- Windows: [Windows](/platforms/windows)
-- Linux: [Linux](/platforms/linux)
-
-## VPS and hosting
-
-- VPS hub: [VPS hosting](/vps)
-- Fly.io: [Fly.io](/install/fly)
-- Hetzner (Docker): [Hetzner](/install/hetzner)
-- GCP (Compute Engine): [GCP](/install/gcp)
-- Azure (Linux VM): [Azure](/install/azure)
-- exe.dev (VM + HTTPS proxy): [exe.dev](/install/exe-dev)
-- EasyRunner (Podman + Caddy): [EasyRunner](/platforms/easyrunner)
-
-## Common links
-
-- Install guide: [Getting Started](/start/getting-started)
-- Gateway runbook: [Gateway](/gateway)
-- Gateway configuration: [Configuration](/gateway/configuration)
-- Service status: `fengming gateway status`
-
-## Gateway service install (CLI)
-
-Use one of these (all supported):
-
-- Wizard (recommended): `fengming onboard --install-daemon`
-- Direct: `fengming gateway install`
-- Configure flow: `fengming configure` → select **Gateway service**
-- Repair/migrate: `fengming doctor` (offers to install or fix the service)
-
-The service target depends on OS:
-
-- Linux/WSL2: systemd user service (`fengming-gateway[-<profile>].service`)
-- Native Windows: Scheduled Task (`FengMing Gateway` or `FengMing Gateway (<profile>)`), with a per-user Startup-folder login item fallback if task creation is denied
-
-## Related
-
-- [Install overview](/install)

package/docs/platforms/linux.md

@@ -1,141 +0,0 @@
----
-summary: "Linux support + companion app status"
-read_when:
-  - Looking for Linux companion app status
-  - Planning platform coverage or contributions
-  - Debugging Linux OOM kills or exit 137 on a VPS or container
-title: "Linux app"
----
-
-The Gateway is fully supported on Linux. **Node is the recommended runtime**.
-Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
-
-Native Linux companion apps are planned. Contributions are welcome if you want to help build one.
-
-## Beginner quick path (VPS)
-
-1. Install Node 24 (recommended; Node 22 LTS, currently `22.19+`, still works for compatibility)
-2. `npm i -g fengming@latest`
-3. `fengming onboard --install-daemon`
-4. From your laptop: `ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
-5. Open `http://127.0.0.1:18789/` and authenticate with the configured shared secret (token by default; password if you set `gateway.auth.mode: "password"`)
-
-Full Linux server guide: [Linux Server](/vps). Step-by-step VPS example: [exe.dev](/install/exe-dev)
-
-## Install
-
-- [Getting Started](/start/getting-started)
-- [Install & updates](/install/updating)
-- Optional flows: [Bun (experimental)](/install/bun), [Nix](/install/nix), [Docker](/install/docker)
-
-## Gateway
-
-- [Gateway runbook](/gateway)
-- [Configuration](/gateway/configuration)
-
-## Gateway service install (CLI)
-
-Use one of these:
-
-```
-fengming onboard --install-daemon
-```
-
-Or:
-
-```
-fengming gateway install
-```
-
-Or:
-
-```
-fengming configure
-```
-
-Select **Gateway service** when prompted.
-
-Repair/migrate:
-
-```
-fengming doctor
-```
-
-## System control (systemd user unit)
-
-FengMing installs a systemd **user** service by default. Use a **system**
-service for shared or always-on servers. `fengming gateway install` and
-`fengming onboard --install-daemon` already render the current canonical unit
-for you; write one by hand only when you need a custom system/service-manager
-setup. The full service guidance lives in the [Gateway runbook](/gateway).
-
-Minimal setup:
-
-Create `~/.config/systemd/user/fengming-gateway[-<profile>].service`:
-
-```
-[Unit]
-Description=FengMing Gateway (profile: <profile>, v<version>)
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-ExecStart=/usr/local/bin/fengming gateway --port 18789
-Restart=always
-RestartSec=5
-TimeoutStopSec=30
-TimeoutStartSec=30
-SuccessExitStatus=0 143
-KillMode=control-group
-
-[Install]
-WantedBy=default.target
-```
-
-Enable it:
-
-```
-systemctl --user enable --now fengming-gateway[-<profile>].service
-```
-
-## Memory pressure and OOM kills
-
-On Linux, the kernel chooses an OOM victim when a host, VM, or container cgroup
-runs out of memory. The Gateway can be a poor victim because it owns long-lived
-sessions and channel connections. FengMing therefore biases transient child
-processes to be killed before the Gateway when possible.
-
-For eligible Linux child spawns, FengMing starts the child through a short
-`/bin/sh` wrapper that raises the child's own `oom_score_adj` to `1000`, then
-`exec`s the real command. This is an unprivileged operation because the child is
-only increasing its own OOM kill likelihood.
-
-Covered child process surfaces include:
-
-- supervisor-managed command children,
-- PTY shell children,
-- MCP stdio server children,
-- FengMing-launched browser/Chrome processes.
-
-The wrapper is Linux-only and is skipped when `/bin/sh` is unavailable. It is
-also skipped if the child env sets `FENGMING_CHILD_OOM_SCORE_ADJ=0`, `false`,
-`no`, or `off`.
-
-To verify a child process:
-
-```bash
-cat /proc/<child-pid>/oom_score_adj
-```
-
-Expected value for covered children is `1000`. The Gateway process should keep
-its normal score, usually `0`.
-
-This does not replace normal memory tuning. If a VPS or container repeatedly
-kills children, increase the memory limit, reduce concurrency, or add stronger
-resource controls such as systemd `MemoryMax=` or container-level memory limits.
-
-## Related
-
-- [Install overview](/install)
-- [Linux server](/vps)
-- [Raspberry Pi](/platforms/raspberry-pi)

package/docs/platforms/mac/bundled-gateway.md

@@ -1,79 +0,0 @@
----
-summary: "Gateway runtime on macOS (external launchd service)"
-read_when:
-  - Packaging FengMing.app
-  - Debugging the macOS gateway launchd service
-  - Installing the gateway CLI for macOS
-title: "Gateway on macOS"
----
-
-FengMing.app no longer bundles Node/Bun or the Gateway runtime. The macOS app
-expects an **external** `fengming` CLI install, does not spawn the Gateway as a
-child process, and manages a per-user launchd service to keep the Gateway
-running (or attaches to an existing local Gateway if one is already running).
-
-## Install the CLI (required for local mode)
-
-Node 24 is the default runtime on the Mac. Node 22 LTS, currently `22.19+`, still works for compatibility. Then install `fengming` globally:
-
-```bash
-npm install -g fengming@<version>
-```
-
-The macOS app's **Install CLI** button runs the same global install flow the app
-uses internally: it prefers npm first, then pnpm, then bun if that is the only
-detected package manager. Node remains the recommended Gateway runtime.
-
-## Launchd (Gateway as LaunchAgent)
-
-Label:
-
-- `ai.fengming.gateway` (or `ai.fengming.<profile>`; legacy `com.fengming.*` may remain)
-
-Plist location (per-user):
-
-- `~/Library/LaunchAgents/ai.fengming.gateway.plist`
-  (or `~/Library/LaunchAgents/ai.fengming.<profile>.plist`)
-
-Manager:
-
-- The macOS app owns LaunchAgent install/update in Local mode.
-- The CLI can also install it: `fengming gateway install`.
-
-Behavior:
-
-- "FengMing Active" enables/disables the LaunchAgent.
-- App quit does **not** stop the gateway (launchd keeps it alive).
-- If a Gateway is already running on the configured port, the app attaches to
-  it instead of starting a new one.
-
-Logging:
-
-- launchd stdout: `~/Library/Logs/fengming/gateway.log` (profiles use `gateway-<profile>.log`)
-- launchd stderr: suppressed
-
-## Version compatibility
-
-The macOS app checks the gateway version against its own version. If they're
-incompatible, update the global CLI to match the app version.
-
-## Smoke check
-
-```bash
-fengming --version
-
-FENGMING_SKIP_CHANNELS=1 \
-FENGMING_SKIP_CANVAS_HOST=1 \
-fengming gateway --port 18999 --bind loopback
-```
-
-Then:
-
-```bash
-fengming gateway call health --url ws://127.0.0.1:18999 --timeout 3000
-```
-
-## Related
-
-- [macOS app](/platforms/macos)
-- [Gateway runbook](/gateway)