fengming 0.3.9 → 0.3.11

package/docs/plugins/codex-native-plugins.md

@@ -1,276 +0,0 @@
----
-summary: "Configure migrated native Codex plugins for Codex-mode FengMing agents"
-title: "Native Codex plugins"
-read_when:
-  - You want Codex-mode FengMing agents to use native Codex plugins
-  - You are migrating source-installed openai-curated Codex plugins
-  - You are troubleshooting codexPlugins, app inventory, destructive actions, or plugin app diagnostics
----
-
-Native Codex plugin support lets a Codex-mode FengMing agent use Codex
-app-server's own app and plugin capabilities inside the same Codex thread that
-handles the FengMing turn.
-
-FengMing does not translate Codex plugins into synthetic `codex_plugin_*`
-FengMing dynamic tools. Plugin calls stay in the native Codex transcript, and
-Codex app-server owns the app-backed MCP execution.
-
-Use this page after the base [Codex harness](/plugins/codex-harness) is working.
-
-## Requirements
-
-- The selected FengMing agent runtime must be the native Codex harness.
-- `plugins.entries.codex.enabled` must be true.
-- `plugins.entries.codex.config.codexPlugins.enabled` must be true.
-- V1 supports only `openai-curated` plugins that migration observed as
-  source-installed in the source Codex home.
-- The target Codex app-server must be able to see the expected marketplace,
-  plugin, and app inventory.
-
-`codexPlugins` has no effect on FengMing runs, normal OpenAI provider runs, ACP
-conversation bindings, or other harnesses because those paths do not create
-Codex app-server threads with native `apps` config.
-
-## Quickstart
-
-Preview migration from the source Codex home:
-
-```bash
-fengming migrate codex --dry-run
-```
-
-Use strict source app verification when you want migration to check source app
-accessibility before planning native plugin activation:
-
-```bash
-fengming migrate codex --dry-run --verify-plugin-apps
-```
-
-Apply the migration when the plan looks right:
-
-```bash
-fengming migrate apply codex --yes
-```
-
-Migration writes explicit `codexPlugins` entries for eligible plugins and calls
-Codex app-server `plugin/install` for selected plugins. A typical migrated
-config looks like this:
-
-```json5
-{
-  plugins: {
-    entries: {
-      codex: {
-        enabled: true,
-        config: {
-          codexPlugins: {
-            enabled: true,
-            allow_destructive_actions: true,
-            plugins: {
-              "google-calendar": {
-                enabled: true,
-                marketplaceName: "openai-curated",
-                pluginName: "google-calendar",
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-After changing `codexPlugins`, new Codex conversations pick up the updated app
-set automatically. Use `/new` or `/reset` to refresh the current conversation.
-A gateway restart is not required for plugin enable or disable changes.
-
-## Manage plugins from chat
-
-Use `/codex plugins` when you want to inspect or change configured native Codex
-plugins from the same chat where you operate the Codex harness:
-
-```text
-/codex plugins
-/codex plugins list
-/codex plugins disable google-calendar
-/codex plugins enable google-calendar
-```
-
-`/codex plugins` is an alias for `/codex plugins list`. The list output shows
-the configured plugin keys, on/off state, Codex plugin name, and marketplace
-from `plugins.entries.codex.config.codexPlugins.plugins`.
-
-`enable` and `disable` write only to FengMing config at
-`~/.fengming/fengming.json`; they do not edit `~/.codex/config.toml` or install
-new Codex plugins. Only the owner or a gateway client with the
-`operator.admin` scope can change plugin state.
-
-Enabling a configured plugin also turns on the global
-`codexPlugins.enabled` switch. If the plugin was written disabled because
-migration returned `auth_required`, reauthorize the app in Codex before enabling
-it in FengMing.
-
-## How native plugin setup works
-
-The integration has three separate states:
-
-- Installed: Codex has the local plugin bundle in the target app-server runtime.
-- Enabled: FengMing config is willing to make the plugin available to Codex
-  harness turns.
-- Accessible: Codex app-server confirms the plugin's app entries are available
-  for the active account and can be mapped to the migrated plugin identity.
-
-Migration is the durable install/eligibility step. During planning, FengMing
-reads source Codex `plugin/read` details and checks that the source Codex
-app-server account response is a ChatGPT subscription account. Non-ChatGPT or
-missing account responses skip app-backed plugins with
-`codex_subscription_required`. By default, migration does not call source
-`app/list`; app-backed source plugins that pass the account gate are planned
-without source app accessibility verification, and account lookup transport
-failures skip with `codex_account_unavailable`. With `--verify-plugin-apps`,
-migration takes a fresh source `app/list` snapshot and requires every owned app
-to be present, enabled, and accessible before planning native activation. In
-that mode, account lookup transport failures fall through to the source
-app-inventory gate. Runtime app inventory is the target-session accessibility
-check after migration. Codex harness session setup then computes a restrictive
-thread app config for the enabled and accessible plugin apps.
-
-Thread app config is computed when FengMing establishes a Codex harness session
-or replaces a stale Codex thread binding. It is not recomputed on every turn, so
-`/codex plugins enable` and `/codex plugins disable` affect new Codex
-conversations. Use `/new` or `/reset` when the current conversation should pick
-up the updated app set.
-
-## V1 support boundary
-
-V1 is intentionally narrow:
-
-- Only `openai-curated` plugins that were already installed in the source Codex
-  app-server inventory are migration-eligible.
-- App-backed source plugins must pass the migration-time subscription gate.
-  `--verify-plugin-apps` adds the source app-inventory gate. Subscription-gated
-  accounts plus, in verification mode, inaccessible, disabled, missing source
-  apps or source app-inventory refresh failures are reported as skipped manual
-  items instead of enabled config entries. Unreadable plugin details are skipped
-  before the source app-inventory gate.
-- Migration writes explicit plugin identities with `marketplaceName` and
-  `pluginName`; it does not write local `marketplacePath` cache paths.
-- `codexPlugins.enabled` is the global enablement switch.
-- There is no `plugins["*"]` wildcard and no config key that grants arbitrary
-  install authority.
-- Unsupported marketplaces, cached plugin bundles, hooks, and Codex config files
-  are preserved in the migration report for manual review.
-
-## App inventory and ownership
-
-FengMing reads Codex app inventory through app-server `app/list`, caches it for
-one hour, and refreshes stale or missing entries asynchronously. The cache is
-in memory only; restarting the CLI or gateway drops it, and FengMing rebuilds it
-from the next `app/list` read.
-
-Migration and runtime use separate cache keys:
-
-- Source migration verification uses the source Codex home and source app-server
-  start options. This runs only when `--verify-plugin-apps` is set, and it
-  forces a fresh source `app/list` traversal for that planning run.
-- Target runtime setup uses the target agent's Codex app-server identity when it
-  builds the Codex thread app config. Plugin activation invalidates that target
-  cache key and then force-refreshes it after `plugin/install`.
-
-A plugin app is exposed only when FengMing can map it back to the migrated
-plugin through stable ownership:
-
-- exact app id from plugin detail
-- known MCP server name
-- unique stable metadata
-
-Display-name-only or ambiguous ownership is excluded until the next inventory
-refresh proves ownership.
-
-## Thread app config
-
-FengMing injects a restrictive `config.apps` patch for the Codex thread:
-`_default` is disabled and only apps owned by enabled migrated plugins are
-enabled.
-
-FengMing sets app-level `destructive_enabled` from the effective global or
-per-plugin `allow_destructive_actions` policy and lets Codex enforce
-destructive tool metadata from its native app tool annotations. The `_default`
-app config is disabled with `open_world_enabled: false`. Enabled plugin apps
-are emitted with `open_world_enabled: true`; FengMing does not expose a separate
-plugin open-world policy knob and does not maintain per-plugin destructive
-tool-name deny lists.
-
-Tool approval mode is automatic by default for plugin apps so non-destructive
-read tools can run without a same-thread approval UI. Destructive tools remain
-controlled by each app's `destructive_enabled` policy.
-
-## Destructive action policy
-
-Destructive plugin elicitations are allowed by default for migrated Codex
-plugins, while unsafe schemas and ambiguous ownership still fail closed:
-
-- Global `allow_destructive_actions` defaults to `true`.
-- Per-plugin `allow_destructive_actions` overrides the global policy for that
-  plugin.
-- When policy is `false`, FengMing returns a deterministic decline.
-- When policy is `true`, FengMing auto-accepts only safe schemas it can map to
-  an approval response, such as a boolean approve field.
-- Missing plugin identity, ambiguous ownership, a missing turn id, a wrong turn
-  id, or an unsafe elicitation schema declines instead of prompting.
-
-## Troubleshooting
-
-**`auth_required`:** migration installed the plugin, but one of its apps still
-needs authentication. The explicit plugin entry is written disabled until you
-reauthorize and enable it.
-
-**`app_inaccessible`, `app_disabled`, or `app_missing`:**
-migration did not install the plugin because the source Codex app inventory did
-not show all owned apps as present, enabled, and accessible while
-`--verify-plugin-apps` was set. Reauthorize or enable the app in Codex, then
-rerun migration with `--verify-plugin-apps`.
-
-**`app_inventory_unavailable`:** migration did not install the plugin because
-strict source app verification was requested and source Codex app inventory
-refresh failed. Fix source Codex app-server access or retry without
-`--verify-plugin-apps` if you accept the faster account-gated plan.
-
-**`codex_subscription_required`:** migration did not install the app-backed
-plugin because the source Codex app-server account was not logged in with a
-ChatGPT subscription account. Log in to the Codex app with subscription auth,
-then rerun migration.
-
-**`codex_account_unavailable`:** migration did not install the app-backed plugin
-because the source Codex app-server account could not be read. Fix source Codex
-app-server auth or rerun with `--verify-plugin-apps` if you want source app
-inventory to decide eligibility when account lookup fails.
-
-**`marketplace_missing` or `plugin_missing`:** the target Codex app-server
-cannot see the expected `openai-curated` marketplace or plugin. Rerun migration
-against the target runtime or inspect Codex app-server plugin status.
-
-**`app_inventory_missing` or `app_inventory_stale`:** app readiness came from an
-empty or stale cache. FengMing schedules an async refresh and excludes plugin
-apps until ownership and readiness are known.
-
-**`app_ownership_ambiguous`:** app inventory only matched by display name, so
-the app is not exposed to the Codex thread.
-
-**Config changed but the agent cannot see the plugin:** use `/codex plugins
-list` to confirm the configured state, then use `/new` or `/reset`. Existing
-Codex thread bindings keep the app config they started with until FengMing
-establishes a new harness session or replaces a stale binding.
-
-**Destructive action is declined:** check the global and per-plugin
-`allow_destructive_actions` values. Even when policy is true, unsafe elicitation
-schemas and ambiguous plugin identity still fail closed.
-
-## Related
-
-- [Codex harness](/plugins/codex-harness)
-- [Codex harness reference](/plugins/codex-harness-reference)
-- [Codex harness runtime](/plugins/codex-harness-runtime)
-- [Configuration reference](/gateway/configuration-reference#codex-harness-plugin-config)
-- [Migrate CLI](/cli/migrate)

package/docs/plugins/community.md

@@ -1,77 +0,0 @@
----
-summary: "Find and publish community-maintained FengMing plugins"
-read_when:
-  - You want to find third-party FengMing plugins
-  - You want to publish or list your own plugin on ClawHub
-title: "Community plugins"
-doc-schema-version: 1
----
-
-Community plugins are third-party packages that extend FengMing with channels,
-tools, providers, hooks, or other capabilities. Use [ClawHub](/clawhub) as the
-primary discovery surface for public community plugins.
-
-## Find plugins
-
-Search ClawHub from the CLI:
-
-```bash
-fengming plugins search "calendar"
-```
-
-Install a ClawHub plugin with an explicit source prefix:
-
-```bash
-fengming plugins install clawhub:<package-name>
-```
-
-npm remains a supported direct-install path during the launch cutover:
-
-```bash
-fengming plugins install npm:<package-name>
-```
-
-Use [Manage plugins](/plugins/manage-plugins) for common install, update,
-inspect, and uninstall examples. Use [`fengming plugins`](/cli/plugins) for the
-full command reference and source-selection rules.
-
-## Publish plugins
-
-Publish public community plugins on ClawHub when you want FengMing users to
-discover and install them. ClawHub owns the live package listing, release
-history, scan status, and install hints; the docs do not maintain a static
-third-party plugin catalog.
-
-```bash
-clawhub package publish your-org/your-plugin --dry-run
-clawhub package publish your-org/your-plugin
-```
-
-Before publishing, make sure the plugin has package metadata, a plugin manifest,
-setup docs, and a clear maintenance owner. ClawHub validates owner scope,
-package name, version, file limits, and source metadata before it creates a
-release, then keeps new releases hidden from normal install and download
-surfaces until review and verification finish.
-
-Use this checklist before you publish:
-
-| Requirement          | Why                                                 |
-| -------------------- | --------------------------------------------------- |
-| Published on ClawHub | Users need `fengming plugins install` hints to work |
-| Public GitHub repo   | Source review, issue tracking, transparency         |
-| Setup and usage docs | Users need to know how to configure it              |
-| Active maintenance   | Recent updates or responsive issue handling         |
-
-Use these pages for the full publishing contract:
-
-- [ClawHub publishing](/clawhub/publishing) explains owners, scopes, releases,
-  review, package validation, and package transfer.
-- [Building plugins](/plugins/building-plugins) shows the plugin package shape
-  and first publish workflow.
-- [Plugin manifest](/plugins/manifest) defines native plugin manifest fields.
-
-## Related
-
-- [Plugins](/tools/plugin) - install, configure, restart, and troubleshoot
-- [Manage plugins](/plugins/manage-plugins) - command examples
-- [ClawHub publishing](/clawhub/publishing) - publish and release rules

package/docs/plugins/compatibility.md

@@ -1,167 +0,0 @@
----
-summary: "Plugin compatibility contracts, deprecation metadata, and migration expectations"
-title: "Plugin compatibility"
-read_when:
-  - You maintain an FengMing plugin
-  - You see a plugin compatibility warning
-  - You are planning a plugin SDK or manifest migration
----
-
-FengMing keeps older plugin contracts wired through named compatibility
-adapters before removing them. This protects existing bundled and external
-plugins while the SDK, manifest, setup, config, and agent runtime contracts
-evolve.
-
-## Compatibility registry
-
-Plugin compatibility contracts are tracked in the core registry at
-`src/plugins/compat/registry.ts`.
-
-Each record has:
-
-- a stable compatibility code
-- status: `active`, `deprecated`, `removal-pending`, or `removed`
-- owner: SDK, config, setup, channel, provider, plugin execution, agent runtime,
-  or core
-- introduction and deprecation dates when applicable
-- replacement guidance
-- docs, diagnostics, and tests that cover the old and new behavior
-
-The registry is the source for maintainer planning and future plugin inspector
-checks. If a plugin-facing behavior changes, add or update the compatibility
-record in the same change that adds the adapter.
-
-Doctor repair and migration compatibility is tracked separately at
-`src/commands/doctor/shared/deprecation-compat.ts`. Those records cover old
-config shapes, install-ledger layouts, and repair shims that may need to stay
-available after the runtime compatibility path is removed.
-
-Release sweeps should check both registries. Do not delete a doctor migration
-just because the matching runtime or config compatibility record expired; first
-verify there is no supported upgrade path that still needs the repair. Also
-revalidate each replacement annotation during release planning because plugin
-ownership and config footprint can change as providers and channels move out of
-core.
-
-## Plugin inspector package
-
-The plugin inspector should live outside the core FengMing repo as a separate
-package/repository backed by the versioned compatibility and manifest
-contracts.
-
-The day-one CLI should be:
-
-```sh
-fengming-plugin-inspector ./my-plugin
-```
-
-It should emit:
-
-- manifest/schema validation
-- the contract compatibility version being checked
-- install/source metadata checks
-- cold-path import checks
-- deprecation and compatibility warnings
-
-Use `--json` for stable machine-readable output in CI annotations. FengMing
-core should expose contracts and fixtures the inspector can consume, but should
-not publish the inspector binary from the main `fengming` package.
-
-### Maintainer acceptance lane
-
-Use Crabbox-backed Blacksmith Testbox for the installable-package acceptance
-lane when validating the external inspector against FengMing plugin packages.
-Run it from a clean FengMing checkout after the package is built:
-
-```sh
-pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @fengming/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
-pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @fengming/plugin-inspector@0.1.0 -- ./extensions/discord --json"
-pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @fengming/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"
-```
-
-Keep this lane opt-in for maintainers because it installs an external npm
-package and may inspect plugin packages cloned outside the repo. The local repo
-guards cover the SDK export map, compatibility registry metadata, deprecated
-SDK-import burn-down, and bundled extension import boundaries; Testbox inspector
-proof covers the package as external plugin authors consume it.
-
-## Deprecation policy
-
-FengMing should not remove a documented plugin contract in the same release
-that introduces its replacement.
-
-The migration sequence is:
-
-1. Add the new contract.
-2. Keep the old behavior wired through a named compatibility adapter.
-3. Emit diagnostics or warnings when plugin authors can act.
-4. Document the replacement and timeline.
-5. Test both old and new paths.
-6. Wait through the announced migration window.
-7. Remove only with explicit breaking-release approval.
-
-Deprecated records must include a warning start date, replacement, docs link,
-and final removal date no more than three months after the warning starts. Do
-not add a deprecated compatibility path with an open-ended removal window unless
-maintainers explicitly decide it is permanent compatibility and mark it `active`
-instead.
-
-## Current compatibility areas
-
-Current compatibility records include:
-
-- legacy broad SDK imports such as `fengming/plugin-sdk/compat`
-- legacy hook-only plugin shapes and `before_agent_start`
-- legacy `api.on("deactivate", ...)` cleanup hook names while plugins migrate to
-  `gateway_stop`
-- legacy `activate(api)` plugin entrypoints while plugins migrate to
-  `register(api)`
-- legacy SDK aliases such as `fengming/extension-api`,
-  `fengming/plugin-sdk/channel-runtime`, `fengming/plugin-sdk/command-auth`
-  status builders, `fengming/plugin-sdk/test-utils` (replaced by focused
-  `fengming/plugin-sdk/*` test subpaths), and the `ClawdbotConfig` /
-  `FengMingSchemaType` type aliases
-- bundled plugin allowlist and enablement behavior
-- legacy provider/channel env-var manifest metadata
-- legacy provider plugin hooks and type aliases while providers move to
-  explicit catalog, auth, thinking, replay, and transport hooks
-- legacy runtime aliases such as `api.runtime.taskFlow`,
-  `api.runtime.subagent.getSession`, `api.runtime.stt`, and deprecated
-  `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
-- legacy memory-plugin split registration while memory plugins move to
-  `registerMemoryCapability`
-- legacy memory-specific embedding provider registration while embedding
-  providers move to `api.registerEmbeddingProvider(...)` and
-  `contracts.embeddingProviders`
-- legacy channel SDK helpers for native message schemas, mention gating,
-  inbound envelope formatting, and approval capability nesting
-- legacy channel route key and comparable-target helper aliases while plugins
-  move to `fengming/plugin-sdk/channel-route`
-- activation hints that are being replaced by manifest contribution ownership
-- `setup-api` runtime fallback while setup descriptors move to cold
-  `setup.requiresRuntime: false` metadata
-- provider `discovery` hooks while provider catalog hooks move to
-  `catalog.run(...)`
-- channel `showConfigured` / `showInSetup` metadata while channel packages move
-  to `fengming.channel.exposure`
-- legacy runtime-policy config keys while doctor migrates operators to
-  `agentRuntime`
-- generated bundled channel config metadata fallback while registry-first
-  `channelConfigs` metadata lands
-- persisted plugin registry disable and install-migration env flags while
-  repair flows migrate operators to `fengming plugins registry --refresh` and
-  `fengming doctor --fix`
-- legacy plugin-owned web search, web fetch, and x_search config paths while
-  doctor migrates them to `plugins.entries.<plugin>.config`
-- legacy `plugins.installs` authored config and bundled plugin load-path
-  aliases while install metadata moves into the state-managed plugin ledger
-
-New plugin code should prefer the replacement listed in the registry and in the
-specific migration guide. Existing plugins can keep using a compatibility path
-until the docs, diagnostics, and release notes announce a removal window.
-
-## Release notes
-
-Release notes should include upcoming plugin deprecations with target dates and
-links to migration docs. That warning needs to happen before a compatibility
-path moves to `removal-pending` or `removed`.