fengming 0.3.9 → 0.3.11

package/docs/plugins/sdk-channel-turn.md

@@ -1,9 +0,0 @@
----
-summary: "Redirect to /plugins/sdk-channel-inbound"
-title: "Channel turn"
----
-
-This page moved to [Channel inbound API](/plugins/sdk-channel-inbound).
-
-The old channel-turn runtime aliases were removed. Plugin code should use
-`runtime.channel.inbound.*`, `channel-inbound`, and `channel-outbound`.

package/docs/plugins/sdk-entrypoints.md

@@ -1,344 +0,0 @@
----
-summary: "Reference for defineToolPlugin, definePluginEntry, defineChannelPluginEntry, and defineSetupPluginEntry"
-title: "Plugin entry points"
-sidebarTitle: "Entry Points"
-read_when:
-  - You need the exact type signature of defineToolPlugin, definePluginEntry, or defineChannelPluginEntry
-  - You want to understand registration mode (full vs setup vs CLI metadata)
-  - You are looking up entry point options
----
-
-Every plugin exports a default entry object. The SDK provides helpers for
-creating them.
-
-For installed plugins, `package.json` should point runtime loading at built
-JavaScript when available:
-
-```json
-{
-  "fengming": {
-    "extensions": ["./src/index.ts"],
-    "runtimeExtensions": ["./dist/index.js"],
-    "setupEntry": "./src/setup-entry.ts",
-    "runtimeSetupEntry": "./dist/setup-entry.js"
-  }
-}
-```
-
-`extensions` and `setupEntry` remain valid source entries for workspace and git
-checkout development. `runtimeExtensions` and `runtimeSetupEntry` are preferred
-when FengMing loads an installed package and let npm packages avoid runtime
-TypeScript compilation. Explicit runtime entries are required: `runtimeSetupEntry`
-requires `setupEntry`, and missing `runtimeExtensions` or `runtimeSetupEntry`
-artifacts fail install/discovery instead of silently falling back to source. If
-an installed package only declares a TypeScript source entry, FengMing will use a
-matching built `dist/*.js` peer when one exists, then fall back to the TypeScript
-source.
-
-All entry paths must stay inside the plugin package directory. Runtime entries
-and inferred built JavaScript peers do not make an escaping `extensions` or
-`setupEntry` source path valid.
-
-<Tip>
-  **Looking for a walkthrough?** See [Tool Plugins](/plugins/tool-plugins),
-  [Channel Plugins](/plugins/sdk-channel-plugins), or
-  [Provider Plugins](/plugins/sdk-provider-plugins) for step-by-step guides.
-</Tip>
-
-## `defineToolPlugin`
-
-**Import:** `fengming/plugin-sdk/tool-plugin`
-
-For simple plugins that only add agent tools. `defineToolPlugin` keeps the
-authoring source small, infers config and tool parameter types from TypeBox
-schemas, wraps plain return values in the FengMing tool-result format, and
-exposes static metadata that `fengming plugins build` writes into the plugin
-manifest.
-
-```typescript
-import { Type } from "typebox";
-import { defineToolPlugin } from "fengming/plugin-sdk/tool-plugin";
-
-export default defineToolPlugin({
-  id: "stock-quotes",
-  name: "Stock Quotes",
-  description: "Fetch stock quotes.",
-  configSchema: Type.Object({
-    apiKey: Type.Optional(Type.String({ description: "API key." })),
-  }),
-  tools: (tool) => [
-    tool({
-      name: "quote",
-      label: "Quote",
-      description: "Fetch a quote.",
-      parameters: Type.Object({
-        symbol: Type.String({ description: "Ticker symbol." }),
-      }),
-      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
-    }),
-  ],
-});
-```
-
-- `configSchema` is optional. When omitted, FengMing uses a strict empty object
-  schema and the generated manifest still includes `configSchema`.
-- `execute` returns a plain string or JSON-serializable value. The helper wraps
-  it as a text tool result with `details`.
-- Tool names are static. `fengming plugins build` derives `contracts.tools`
-  from the declared tools, so authors do not duplicate names by hand.
-- Runtime loading stays strict. Installed plugins still need
-  `fengming.plugin.json` and `package.json` `fengming.extensions`; FengMing does
-  not execute plugin code to infer missing manifest data.
-
-## `definePluginEntry`
-
-**Import:** `fengming/plugin-sdk/plugin-entry`
-
-For provider plugins, advanced tool plugins, hook plugins, and anything that is
-**not** a messaging channel.
-
-```typescript
-import { definePluginEntry } from "fengming/plugin-sdk/plugin-entry";
-
-export default definePluginEntry({
-  id: "my-plugin",
-  name: "My Plugin",
-  description: "Short summary",
-  register(api) {
-    api.registerProvider({
-      /* ... */
-    });
-    api.registerTool({
-      /* ... */
-    });
-  },
-});
-```
-
-| Field          | Type                                                             | Required | Default             |
-| -------------- | ---------------------------------------------------------------- | -------- | ------------------- |
-| `id`           | `string`                                                         | Yes      | -                   |
-| `name`         | `string`                                                         | Yes      | -                   |
-| `description`  | `string`                                                         | Yes      | -                   |
-| `kind`         | `string`                                                         | No       | -                   |
-| `configSchema` | `FengMingPluginConfigSchema \| () => FengMingPluginConfigSchema` | No       | Empty object schema |
-| `register`     | `(api: FengMingPluginApi) => void`                               | Yes      | -                   |
-
-- `id` must match your `fengming.plugin.json` manifest.
-- `kind` is for exclusive slots: `"memory"` or `"context-engine"`.
-- `configSchema` can be a function for lazy evaluation.
-- FengMing resolves and memoizes that schema on first access, so expensive schema
-  builders only run once.
-
-## `defineChannelPluginEntry`
-
-**Import:** `fengming/plugin-sdk/channel-core`
-
-Wraps `definePluginEntry` with channel-specific wiring. Automatically calls
-`api.registerChannel({ plugin })`, exposes an optional root-help CLI metadata
-seam, and gates `registerFull` on registration mode.
-
-```typescript
-import { defineChannelPluginEntry } from "fengming/plugin-sdk/channel-core";
-
-export default defineChannelPluginEntry({
-  id: "my-channel",
-  name: "My Channel",
-  description: "Short summary",
-  plugin: myChannelPlugin,
-  setRuntime: setMyRuntime,
-  registerCliMetadata(api) {
-    api.registerCli(/* ... */);
-  },
-  registerFull(api) {
-    api.registerGatewayMethod(/* ... */);
-  },
-});
-```
-
-| Field                 | Type                                                             | Required | Default             |
-| --------------------- | ---------------------------------------------------------------- | -------- | ------------------- |
-| `id`                  | `string`                                                         | Yes      | -                   |
-| `name`                | `string`                                                         | Yes      | -                   |
-| `description`         | `string`                                                         | Yes      | -                   |
-| `plugin`              | `ChannelPlugin`                                                  | Yes      | -                   |
-| `configSchema`        | `FengMingPluginConfigSchema \| () => FengMingPluginConfigSchema` | No       | Empty object schema |
-| `setRuntime`          | `(runtime: PluginRuntime) => void`                               | No       | -                   |
-| `registerCliMetadata` | `(api: FengMingPluginApi) => void`                               | No       | -                   |
-| `registerFull`        | `(api: FengMingPluginApi) => void`                               | No       | -                   |
-
-- `setRuntime` is called during registration so you can store the runtime reference
-  (typically via `createPluginRuntimeStore`). It is skipped during CLI metadata
-  capture.
-- `registerCliMetadata` runs during `api.registrationMode === "cli-metadata"`,
-  `api.registrationMode === "discovery"`, and
-  `api.registrationMode === "full"`.
-  Use it as the canonical place for channel-owned CLI descriptors so root help
-  stays non-activating, discovery snapshots include static command metadata, and
-  normal CLI command registration remains compatible with full plugin loads.
-- Discovery registration is non-activating, not import-free. FengMing may
-  evaluate the trusted plugin entry and channel plugin module to build the
-  snapshot, so keep top-level imports side-effect-free and put sockets,
-  clients, workers, and services behind `"full"`-only paths.
-- `registerFull` only runs when `api.registrationMode === "full"`. It is skipped
-  during setup-only loading.
-- Like `definePluginEntry`, `configSchema` can be a lazy factory and FengMing
-  memoizes the resolved schema on first access.
-- For plugin-owned root CLI commands, prefer `api.registerCli(..., { descriptors: [...] })`
-  when you want the command to stay lazy-loaded without disappearing from the
-  root CLI parse tree. For paired-node feature commands, prefer
-  `api.registerNodeCliFeature(...)` so the command lands under `fengming nodes`.
-  For other nested plugin commands, add `parentPath` and register commands on
-  the `program` object passed to the registrar; FengMing resolves it to the
-  parent command before calling the plugin. For channel plugins, prefer
-  registering those descriptors from `registerCliMetadata(...)` and keep
-  `registerFull(...)` focused on runtime-only work.
-- If `registerFull(...)` also registers gateway RPC methods, keep them on a
-  plugin-specific prefix. Reserved core admin namespaces (`config.*`,
-  `exec.approvals.*`, `wizard.*`, `update.*`) are always coerced to
-  `operator.admin`.
-
-## `defineSetupPluginEntry`
-
-**Import:** `fengming/plugin-sdk/channel-core`
-
-For the lightweight `setup-entry.ts` file. Returns just `{ plugin }` with no
-runtime or CLI wiring.
-
-```typescript
-import { defineSetupPluginEntry } from "fengming/plugin-sdk/channel-core";
-
-export default defineSetupPluginEntry(myChannelPlugin);
-```
-
-FengMing loads this instead of the full entry when a channel is disabled,
-unconfigured, or when deferred loading is enabled. See
-[Setup and Config](/plugins/sdk-setup#setup-entry) for when this matters.
-
-In practice, pair `defineSetupPluginEntry(...)` with the narrow setup helper
-families:
-
-- `fengming/plugin-sdk/setup-runtime` for runtime-safe setup helpers such as
-  `createSetupTranslator`, import-safe setup patch adapters, lookup-note output,
-  `promptResolvedAllowFrom`, `splitSetupEntries`, and delegated setup proxies
-- `fengming/plugin-sdk/channel-setup` for optional-install setup surfaces
-- `fengming/plugin-sdk/setup-tools` for setup/install CLI/archive/docs helpers
-
-Keep heavy SDKs, CLI registration, and long-lived runtime services in the full
-entry.
-
-Bundled workspace channels that split setup and runtime surfaces can use
-`defineBundledChannelSetupEntry(...)` from
-`fengming/plugin-sdk/channel-entry-contract` instead. That contract lets the
-setup entry keep setup-safe plugin/secrets exports while still exposing a
-runtime setter:
-
-```typescript
-import { defineBundledChannelSetupEntry } from "fengming/plugin-sdk/channel-entry-contract";
-
-export default defineBundledChannelSetupEntry({
-  importMetaUrl: import.meta.url,
-  plugin: {
-    specifier: "./channel-plugin-api.js",
-    exportName: "myChannelPlugin",
-  },
-  runtime: {
-    specifier: "./runtime-api.js",
-    exportName: "setMyChannelRuntime",
-  },
-  registerSetupRuntime(api) {
-    api.registerHttpRoute({
-      path: "/my-channel/events",
-      auth: "plugin",
-      handler: async (req, res) => {
-        /* setup-safe route */
-      },
-    });
-  },
-});
-```
-
-Use that bundled contract only when setup flows truly need a lightweight runtime
-setter or setup-safe gateway surface before the full channel entry loads.
-`registerSetupRuntime` runs only for `"setup-runtime"` loads; keep it limited to
-config-only routes or methods that must exist before deferred full activation.
-
-## Registration mode
-
-`api.registrationMode` tells your plugin how it was loaded:
-
-| Mode              | When                              | What to register                                                                                                        |
-| ----------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `"full"`          | Normal gateway startup            | Everything                                                                                                              |
-| `"discovery"`     | Read-only capability discovery    | Channel registration plus static CLI descriptors; entry code may load, but skip sockets, workers, clients, and services |
-| `"setup-only"`    | Disabled/unconfigured channel     | Channel registration only                                                                                               |
-| `"setup-runtime"` | Setup flow with runtime available | Channel registration plus only the lightweight runtime needed before the full entry loads                               |
-| `"cli-metadata"`  | Root help / CLI metadata capture  | CLI descriptors only                                                                                                    |
-
-`defineChannelPluginEntry` handles this split automatically. If you use
-`definePluginEntry` directly for a channel, check mode yourself:
-
-```typescript
-register(api) {
-  if (
-    api.registrationMode === "cli-metadata" ||
-    api.registrationMode === "discovery" ||
-    api.registrationMode === "full"
-  ) {
-    api.registerCli(/* ... */);
-    if (api.registrationMode === "cli-metadata") return;
-  }
-
-  api.registerChannel({ plugin: myPlugin });
-  if (api.registrationMode !== "full") return;
-
-  // Heavy runtime-only registrations
-  api.registerService(/* ... */);
-}
-```
-
-Discovery mode builds a non-activating registry snapshot. It may still evaluate
-the plugin entry and the channel plugin object so FengMing can register channel
-capabilities and static CLI descriptors. Treat module evaluation in discovery as
-trusted but lightweight: no network clients, subprocesses, listeners, database
-connections, background workers, credential reads, or other live runtime side
-effects at top level.
-
-Treat `"setup-runtime"` as the window where setup-only startup surfaces must
-exist without re-entering the full bundled channel runtime. Good fits are
-channel registration, setup-safe HTTP routes, setup-safe gateway methods, and
-delegated setup helpers. Heavy background services, CLI registrars, and
-provider/client SDK bootstraps still belong in `"full"`.
-
-For CLI registrars specifically:
-
-- use `descriptors` when the registrar owns one or more root commands and you
-  want FengMing to lazy-load the real CLI module on first invocation
-- make sure those descriptors cover every top-level command root exposed by the
-  registrar
-- keep descriptor command names to letters, numbers, hyphen, and underscore,
-  starting with a letter or number; FengMing rejects descriptor names outside
-  that shape and strips terminal control sequences from descriptions before
-  rendering help
-- use `commands` alone only for eager compatibility paths
-
-## Plugin shapes
-
-FengMing classifies loaded plugins by their registration behavior:
-
-| Shape                 | Description                                        |
-| --------------------- | -------------------------------------------------- |
-| **plain-capability**  | One capability type (e.g. provider-only)           |
-| **hybrid-capability** | Multiple capability types (e.g. provider + speech) |
-| **hook-only**         | Only hooks, no capabilities                        |
-| **non-capability**    | Tools/commands/services but no capabilities        |
-
-Use `fengming plugins inspect <id>` to see a plugin's shape.
-
-## Related
-
-- [SDK Overview](/plugins/sdk-overview) - registration API and subpath reference
-- [Runtime Helpers](/plugins/sdk-runtime) - `api.runtime` and `createPluginRuntimeStore`
-- [Setup and Config](/plugins/sdk-setup) - manifest, setup entry, deferred loading
-- [Channel Plugins](/plugins/sdk-channel-plugins) - building the `ChannelPlugin` object
-- [Provider Plugins](/plugins/sdk-provider-plugins) - provider registration and hooks