fengming 0.3.9 → 0.3.11

package/docs/plugins/message-presentation.md

@@ -1,473 +0,0 @@
----
-summary: "Semantic message cards, buttons, selects, fallback text, and delivery hints for channel plugins"
-title: "Message presentation"
-read_when:
-  - Adding or modifying message card, button, or select rendering
-  - Building a channel plugin that supports rich outbound messages
-  - Changing message tool presentation or delivery capabilities
-  - Debugging provider-specific card/block/component rendering regressions
----
-
-Message presentation is FengMing's shared contract for rich outbound chat UI.
-It lets agents, CLI commands, approval flows, and plugins describe the message
-intent once, while each channel plugin renders the best native shape it can.
-
-Use presentation for portable message UI:
-
-- text sections
-- small context/footer text
-- dividers
-- buttons
-- select menus
-- card title and tone
-
-Do not add new provider-native fields such as Discord `components`, Slack
-`blocks`, Telegram `buttons`, Teams `card`, or Feishu `card` to the shared
-message tool. Those are renderer outputs owned by the channel plugin.
-
-## Contract
-
-Plugin authors import the public contract from:
-
-```ts
-import type {
-  MessagePresentation,
-  ReplyPayloadDelivery,
-} from "fengming/plugin-sdk/interactive-runtime";
-```
-
-Shape:
-
-```ts
-type MessagePresentation = {
-  title?: string;
-  tone?: "neutral" | "info" | "success" | "warning" | "danger";
-  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;
-  webApp?: { url: string };
-  /** @deprecated Use webApp. Accepted for legacy JSON payloads only. */
-  web_app?: { url: string };
-  priority?: number;
-  disabled?: boolean;
-  reusable?: boolean;
-  style?: "primary" | "secondary" | "success" | "danger";
-};
-
-type MessagePresentationOption = {
-  label: string;
-  value: string;
-};
-
-type ReplyPayloadDelivery = {
-  pin?:
-    | boolean
-    | {
-        enabled: boolean;
-        notify?: boolean;
-        required?: boolean;
-      };
-};
-```
-
-Button semantics:
-
-- `value` is an application action value routed back through the channel's
-  existing interaction path when the channel supports clickable controls.
-- `url` is a link button. It can exist without `value`.
-- `webApp` describes a channel-native web app button. Telegram renders this
-  as `web_app` and only supports it in private chats. `web_app` is still
-  accepted in loose JSON payloads for compatibility, but TypeScript producers
-  should use `webApp`.
-- `label` is required and is also used in text fallback.
-- `style` is advisory. Renderers should map unsupported styles to a safe
-  default, not fail the send.
-- `priority` is optional. When a channel advertises action limits and controls
-  must be dropped, core keeps higher-priority buttons first and preserves
-  original order among equal priority buttons. When all controls fit, authored
-  order is preserved.
-- `disabled` is optional. Channels must opt in with `supportsDisabled`; otherwise
-  core degrades the disabled control to non-interactive fallback text.
-- `reusable` is optional. Channels that support reusable native callbacks may
-  keep the action available after a successful interaction. Use it for
-  repeatable or idempotent actions such as refresh, inspect, or more details;
-  leave it unset for normal one-shot approvals and destructive actions.
-
-Select semantics:
-
-- `options[].value` is the selected application value.
-- `placeholder` is advisory and may be ignored by channels without native
-  select support.
-- If a channel does not support selects, fallback text lists the labels.
-
-## Producer examples
-
-Simple card:
-
-```json
-{
-  "title": "Deploy approval",
-  "tone": "warning",
-  "blocks": [
-    { "type": "text", "text": "Canary is ready to promote." },
-    { "type": "context", "text": "Build 1234, staging passed." },
-    {
-      "type": "buttons",
-      "buttons": [
-        { "label": "Approve", "value": "deploy:approve", "style": "success" },
-        { "label": "Decline", "value": "deploy:decline", "style": "danger" }
-      ]
-    }
-  ]
-}
-```
-
-URL-only link button:
-
-```json
-{
-  "blocks": [
-    { "type": "text", "text": "Release notes are ready." },
-    {
-      "type": "buttons",
-      "buttons": [{ "label": "Open notes", "url": "https://example.com/release" }]
-    }
-  ]
-}
-```
-
-Telegram Mini App button:
-
-```json
-{
-  "blocks": [
-    {
-      "type": "buttons",
-      "buttons": [{ "label": "Launch", "web_app": { "url": "https://example.com/app" } }]
-    }
-  ]
-}
-```
-
-Select menu:
-
-```json
-{
-  "title": "Choose environment",
-  "blocks": [
-    {
-      "type": "select",
-      "placeholder": "Environment",
-      "options": [
-        { "label": "Canary", "value": "env:canary" },
-        { "label": "Production", "value": "env:prod" }
-      ]
-    }
-  ]
-}
-```
-
-CLI send:
-
-```bash
-fengming message send --channel slack \
-  --target channel:C123 \
-  --message "Deploy approval" \
-  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Canary is ready."},{"type":"buttons","buttons":[{"label":"Approve","value":"deploy:approve","style":"success"},{"label":"Decline","value":"deploy:decline","style":"danger"}]}]}'
-```
-
-Pinned delivery:
-
-```bash
-fengming message send --channel telegram \
-  --target -1001234567890 \
-  --message "Topic opened" \
-  --pin
-```
-
-Pinned delivery with explicit JSON:
-
-```json
-{
-  "pin": {
-    "enabled": true,
-    "notify": true,
-    "required": false
-  }
-}
-```
-
-## Renderer contract
-
-Channel plugins declare render support on their outbound adapter:
-
-```ts
-const adapter: ChannelOutboundAdapter = {
-  deliveryMode: "direct",
-  presentationCapabilities: {
-    supported: true,
-    buttons: true,
-    selects: true,
-    context: true,
-    divider: true,
-    limits: {
-      actions: {
-        maxActions: 25,
-        maxActionsPerRow: 5,
-        maxRows: 5,
-        maxLabelLength: 80,
-        maxValueBytes: 100,
-        supportsStyles: true,
-        supportsDisabled: false,
-      },
-      selects: {
-        maxOptions: 25,
-        maxLabelLength: 100,
-        maxValueBytes: 100,
-      },
-      text: {
-        maxLength: 2000,
-        encoding: "characters",
-        markdownDialect: "discord-markdown",
-      },
-    },
-  },
-  deliveryCapabilities: {
-    pin: true,
-  },
-  renderPresentation({ payload, presentation, ctx }) {
-    return renderNativePayload(payload, presentation, ctx);
-  },
-  async pinDeliveredMessage({ target, messageId, pin }) {
-    await pinNativeMessage(target, messageId, { notify: pin.notify === true });
-  },
-};
-```
-
-Capability booleans describe what the renderer can make interactive. Optional
-`limits` describe the generic envelope core can adapt before calling the
-renderer:
-
-```ts
-type ChannelPresentationCapabilities = {
-  supported?: boolean;
-  buttons?: boolean;
-  selects?: boolean;
-  context?: boolean;
-  divider?: boolean;
-  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;
-    };
-  };
-};
-```
-
-Core applies generic limits to semantic controls before rendering. Renderers
-still own final provider-specific validation and clipping for native block
-count, card size, URL limits, and provider quirks that cannot be expressed in
-the generic contract. If limits remove every control from a block, core keeps
-the labels as non-interactive context text so the delivered message still has a
-visible fallback.
-
-## Core render flow
-
-When a `ReplyPayload` or message action includes `presentation`, core:
-
-1. Normalizes the presentation payload.
-2. Resolves the target channel's outbound adapter.
-3. Reads `presentationCapabilities`.
-4. Applies generic capability limits such as action count, label length, and
-   select option count when the adapter advertises them.
-5. Calls `renderPresentation` when the adapter can render the payload.
-6. Falls back to conservative text when the adapter is absent or cannot render.
-7. Sends the resulting payload through the normal channel delivery path.
-8. Applies delivery metadata such as `delivery.pin` after the first successful
-   sent message.
-
-Core owns fallback behavior so producers can stay channel-agnostic. Channel
-plugins own native rendering and interaction handling.
-
-## Degradation rules
-
-Presentation must be safe to send on limited channels.
-
-Fallback text includes:
-
-- `title` as the first line
-- `text` blocks as normal paragraphs
-- `context` blocks as compact context lines
-- `divider` blocks as a visual separator
-- button labels, including URLs for link buttons
-- select option labels
-
-Unsupported native controls should degrade rather than fail the whole send.
-Examples:
-
-- Telegram with inline buttons disabled sends text fallback.
-- A channel without select support lists select options as text.
-- A URL-only button becomes either a native link button or a fallback URL line.
-- Optional pin failures do not fail the delivered message.
-
-The main exception is `delivery.pin.required: true`; if pinning is requested as
-required and the channel cannot pin the sent message, delivery reports failure.
-
-## Provider mapping
-
-Current bundled renderers:
-
-| Channel         | Native render target                | Notes                                                                                                                                             |
-| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Discord         | Components and component containers | Preserves legacy `channelData.discord.components` for existing provider-native payload producers, but new shared sends should use `presentation`. |
-| Slack           | Block Kit                           | Preserves legacy `channelData.slack.blocks` for existing provider-native payload producers, but new shared sends should use `presentation`.       |
-| Telegram        | Text plus inline keyboards          | Buttons/selects require inline button capability for the target surface; otherwise text fallback is used.                                         |
-| Mattermost      | Text plus interactive props         | Other blocks degrade to text.                                                                                                                     |
-| Microsoft Teams | Adaptive Cards                      | Plain `message` text is included with the card when both are provided.                                                                            |
-| Feishu          | Interactive cards                   | Card header can use `title`; body avoids duplicating that title.                                                                                  |
-| Plain channels  | Text fallback                       | Channels without a renderer still get readable output.                                                                                            |
-
-Provider-native payload compatibility is a transition affordance for existing
-reply producers. It is not a reason to add new shared native fields.
-
-## Presentation vs InteractiveReply
-
-`InteractiveReply` is the older internal subset used by approval and interaction
-helpers. It supports:
-
-- text
-- buttons
-- selects
-
-`MessagePresentation` is the canonical shared send contract. It adds:
-
-- title
-- tone
-- context
-- divider
-- URL-only buttons
-- generic delivery metadata through `ReplyPayload.delivery`
-
-Use helpers from `fengming/plugin-sdk/interactive-runtime` when bridging older
-code:
-
-```ts
-import {
-  adaptMessagePresentationForChannel,
-  applyPresentationActionLimits,
-  interactiveReplyToPresentation,
-  normalizeMessagePresentation,
-  presentationPageSize,
-  presentationToInteractiveControlsReply,
-  presentationToInteractiveReply,
-  renderMessagePresentationFallbackText,
-} from "fengming/plugin-sdk/interactive-runtime";
-```
-
-New code should accept or produce `MessagePresentation` directly. Existing
-`interactive` payloads are a deprecated subset of `presentation`; runtime
-support remains for older producers.
-
-The legacy `InteractiveReply*` types and conversion helpers are marked
-`@deprecated` in the SDK:
-
-- `InteractiveReply`, `InteractiveReplyBlock`, `InteractiveReplyButton`,
-  `InteractiveReplyOption`, `InteractiveReplySelectBlock`, and
-  `InteractiveReplyTextBlock`
-- `normalizeInteractiveReply(...)`
-- `hasInteractiveReplyBlocks(...)`
-- `interactiveReplyToPresentation(...)`
-- `presentationToInteractiveReply(...)`
-- `presentationToInteractiveControlsReply(...)`
-- `resolveInteractiveTextFallback(...)`
-- `reduceInteractiveReply(...)`
-
-`presentationToInteractiveReply(...)` and
-`presentationToInteractiveControlsReply(...)` remain available as renderer
-bridges for legacy channel implementations. New producer code should not call
-them; send `presentation` and let core/channel adaptation handle rendering.
-
-Approval helpers also have presentation-first replacements:
-
-- use `buildApprovalPresentationFromActionDescriptors(...)` instead of
-  `buildApprovalInteractiveReplyFromActionDescriptors(...)`
-- use `buildApprovalPresentation(...)` instead of
-  `buildApprovalInteractiveReply(...)`
-- use `buildExecApprovalPresentation(...)` instead of
-  `buildExecApprovalInteractiveReply(...)`
-
-`renderMessagePresentationFallbackText(...)` returns an empty string for
-presentation blocks that have no text fallback, such as a divider-only
-presentation. Transports that require a non-empty send body can pass
-`emptyFallback` to opt into a minimal body without changing the default fallback
-contract.
-
-## Delivery pin
-
-Pinning is delivery behavior, not presentation. Use `delivery.pin` instead of
-provider-native fields such as `channelData.telegram.pin`.
-
-Semantics:
-
-- `pin: true` pins the first successfully delivered message.
-- `pin.notify` defaults to `false`.
-- `pin.required` defaults to `false`.
-- Optional pin failures degrade and leave the sent message intact.
-- Required pin failures fail delivery.
-- Chunked messages pin the first delivered chunk, not the tail chunk.
-
-Manual `pin`, `unpin`, and `pins` message actions still exist for existing
-messages where the provider supports those operations.
-
-## Plugin author checklist
-
-- Declare `presentation` from `describeMessageTool(...)` when the channel can
-  render or safely degrade semantic presentation.
-- Add `presentationCapabilities` to the runtime outbound adapter.
-- Implement `renderPresentation` in runtime code, not control-plane plugin
-  setup code.
-- Keep native UI libraries out of hot setup/catalog paths.
-- Declare generic capability limits on `presentationCapabilities.limits` when
-  they are known.
-- Preserve final platform limits in the renderer and tests.
-- Add fallback tests for unsupported buttons, selects, URL buttons, title/text
-  duplication, and mixed `message` plus `presentation` sends.
-- Add delivery pin support through `deliveryCapabilities.pin` and
-  `pinDeliveredMessage` only when the provider can pin the sent message id.
-- Do not expose new provider-native card/block/component/button fields through
-  the shared message action schema.
-
-## Related docs
-
-- [Message CLI](/cli/message)
-- [Plugin SDK Overview](/plugins/sdk-overview)
-- [Plugin Architecture](/plugins/architecture-internals#message-tool-schemas)
-- [Channel Presentation Refactor Plan](/plan/ui-channels)

package/docs/plugins/oc-path.md

@@ -1,166 +0,0 @@
----
-summary: "Bundled `oc-path` plugin: ships the `fengming path` CLI for the `oc://` workspace-file addressing scheme"
-read_when:
-  - You want to inspect or edit a single leaf inside a workspace file from the terminal
-  - You are scripting against workspace state and need a stable, kind-agnostic addressing scheme
-  - You are deciding whether to enable the optional `oc-path` plugin on a self-hosted Gateway
-title: "OC Path plugin"
----
-
-The bundled `oc-path` plugin adds the [`fengming path`](/cli/path) CLI for the
-`oc://` workspace-file addressing scheme. It ships in the FengMing repo under
-`extensions/oc-path/` but is opt-in — install/build leaves it dormant until you
-enable it.
-
-`oc://` addresses point at a single leaf (or a wildcard set of leaves) inside
-a workspace file. The plugin understands four kinds of files today:
-
-- **markdown** (`.md`, `.mdx`): frontmatter, sections, items, fields
-- **jsonc** (`.jsonc`, `.json5`, `.json`): comments and formatting preserved
-- **jsonl** (`.jsonl`, `.ndjson`): line-oriented records
-- **yaml** (`.yaml`, `.yml`, `.lobster`): map/sequence/scalar nodes through the
-  YAML document API
-
-Self-hosters and editor extensions use the CLI to read or write a single leaf
-without scripting against the SDK directly; agents and hooks treat it as a
-deterministic substrate so byte-fidelity round-trips and the redaction
-sentinel guard apply uniformly across kinds.
-
-## Why enable it
-
-Enable `oc-path` when you want scripts, hooks, or local agent tooling to point
-at a precise piece of workspace state without inventing a parser for each file
-shape. A single `oc://` address can name a markdown frontmatter key, a section
-item, a JSONC config leaf, a JSONL event field, or a YAML workflow step.
-
-That matters for maintainer workflows where the change should be small,
-auditable, and repeatable: inspect one value, find matching records, dry-run a
-write, then apply only that leaf while leaving comments, line endings, and
-nearby formatting alone. Keeping this as an opt-in plugin gives power users the
-addressing substrate without putting parser dependencies or CLI surface into
-core for installs that never need it.
-
-Common reasons to enable it:
-
-- **Local automation**: shell scripts can resolve or update one workspace value
-  with `fengming path … --json` instead of carrying separate markdown, JSONC,
-  JSONL, and YAML parsing code.
-- **Agent-visible edits**: an agent can show a dry-run diff for one addressed
-  leaf before writing, which is easier to review than a free-form file rewrite.
-- **Editor integrations**: an editor can map `oc://AGENTS.md/tools/gh` to the
-  exact markdown node and line number without guessing from heading text.
-- **Diagnostics**: `emit` round-trips a file through the parser and emitter, so
-  you can check whether a file kind is byte-stable before relying on automated
-  edits.
-
-Concrete examples:
-
-```bash
-# Is the GitHub plugin enabled in this config?
-fengming path resolve 'oc://config.jsonc/plugins/github/enabled' --json
-
-# Which tool-call names appear in this session log?
-fengming path find 'oc://session.jsonl/[event=tool_call]/name' --json
-
-# What bytes would this tiny config edit write?
-fengming path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run
-```
-
-The plugin is intentionally not the owner of higher-level semantics. Memory
-plugins still own memory writes, config commands still own full config
-management, and LKG logic still owns restore/promotion. `oc-path` is the narrow
-addressing and byte-preserving file operation layer those higher-level tools
-can build around.
-
-## Where it runs
-
-The plugin runs **in-process inside the `fengming` CLI** on the host where you
-invoke the command. It does not need a running Gateway and does not open any
-network sockets — every verb is a pure transform over a file you point it at.
-
-The plugin metadata lives in `extensions/oc-path/fengming.plugin.json`:
-
-```json
-{
-  "id": "oc-path",
-  "name": "OC Path",
-  "activation": {
-    "onStartup": false,
-    "onCommands": ["path"]
-  },
-  "commandAliases": [{ "name": "path", "kind": "cli" }]
-}
-```
-
-`onStartup: false` keeps the plugin out of the Gateway hot path. `onCommands:
-["path"]` tells the CLI to load the plugin lazily the first time you run
-`fengming path …`, so installs that never use the verb pay no cost.
-
-## Enable
-
-```bash
-fengming plugins enable oc-path
-```
-
-Restart the Gateway (if you run one) so the manifest snapshot picks up the new
-state. Bare `fengming path` invocations work immediately on the same host —
-the CLI loads the plugin on demand.
-
-Disable with:
-
-```bash
-fengming plugins disable oc-path
-```
-
-## Dependencies
-
-All parser dependencies are plugin-local — enabling `oc-path` does not pull
-new packages into the core runtime:
-
-| Dependency     | Purpose                                                                |
-| -------------- | ---------------------------------------------------------------------- |
-| `commander`    | Subcommand wiring for `resolve`, `find`, `set`, `validate`, `emit`.    |
-| `jsonc-parser` | JSONC parse + leaf edits with comments and trailing commas kept.       |
-| `markdown-it`  | Markdown tokenization for the section / item / field model.            |
-| `yaml`         | YAML `Document` parse / emit / edit with comments and flow style kept. |
-
-JSONL stays hand-rolled — line-oriented parsing is simpler than any
-dependency, and the per-line JSONC parse already goes through `jsonc-parser`.
-
-## What it provides
-
-| Surface                        | Provided by                                             |
-| ------------------------------ | ------------------------------------------------------- |
-| `fengming path` CLI            | `extensions/oc-path/cli-registration.ts`                |
-| `oc://` parser / formatter     | `extensions/oc-path/src/oc-path/oc-path.ts`             |
-| Per-kind parse / emit / edit   | `extensions/oc-path/src/oc-path/{md,jsonc,jsonl,yaml}`  |
-| Universal resolve / find / set | `extensions/oc-path/src/oc-path/{resolve,find,edit}.ts` |
-| Redaction-sentinel guard       | `extensions/oc-path/src/oc-path/sentinel.ts`            |
-
-The CLI is the only public surface today. The substrate verbs are private to
-the plugin; consumers use the CLI (or build their own plugin against the SDK).
-
-## Relationship to other plugins
-
-- **`memory-*`**: memory writes go through the memory plugins, not `oc-path`.
-  `oc-path` is a generic file substrate; memory plugins layer their own
-  semantics on top.
-- **LKG**: `path` does not know about Last-Known-Good config restore. If a
-  file is LKG-tracked, the next `observe` call decides whether to promote or
-  recover; `set --batch` for atomic multi-set through the LKG promote/recover
-  lifecycle is planned alongside the LKG-recovery substrate.
-
-## Safety
-
-`set` writes raw bytes through the substrate's emit path, which applies the
-redaction-sentinel guard automatically. A leaf carrying
-`__FENGMING_REDACTED__` (verbatim or as a substring) is refused at write time
-with `OC_EMIT_SENTINEL`. The CLI also scrubs the literal sentinel from any
-human or JSON output it prints, replacing it with `[REDACTED]` so terminal
-captures and pipelines never leak the marker.
-
-## Related
-
-- [`fengming path` CLI reference](/cli/path)
-- [Manage plugins](/plugins/manage-plugins)
-- [Building plugins](/plugins/building-plugins)