fengming 0.3.9 → 0.3.11

package/docs/refactor/ingress-core.md

@@ -1,341 +0,0 @@
----
-summary: "Deletion-first plan for moving repeated channel ingress glue into core."
-read_when:
-  - Auditing why the channel ingress refactor added too much code
-  - Moving route, command, event, activation, or access-group policy from bundled plugins into core
-  - Reviewing whether a channel ingress helper actually deletes bundled plugin code
-title: "Ingress core deletion plan"
-sidebarTitle: "Ingress core deletion"
----
-
-# Ingress core deletion plan
-
-The ingress refactor is not healthy while it adds thousands of net lines. Core
-centralization only counts when bundled plugin production code gets smaller and
-old third-party SDK compatibility is quarantined to SDK/core shims.
-
-Desired runtime shape:
-
-```text
-bundled plugin event
-  -> extract platform facts locally
-  -> resolve shared ingress once when facts are available
-  -> branch on generic ingress projections/outcomes
-  -> perform platform side effects locally
-
-old third-party helper
-  -> SDK compatibility shim
-  -> shared ingress-compatible projection where possible
-  -> old return shape preserved
-```
-
-Bundled plugins should not translate ingress back into local `AccessResult`,
-`GroupAccessDecision`, `CommandAuthDecision`, `DmCommandAccess`, or
-`{ allowed, reasonCode }` shapes unless that type is public plugin API.
-
-## Budget
-
-Measured against the PR merge-base with `origin/main`, including untracked
-files.
-
-```text
-merge-base            1671e7532adb
-
-current:
-core production       +3,922 / -546    = +3,376
-docs                  +601 / -17       = +584
-other                 +145 / -2        = +143
-plugin production     +4,148 / -5,388  = -1,240
-tests                 +2,326 / -2,414  = -88
-total                 +11,142 / -8,367 = +2,775
-
-required:
-plugin production     <= -1,500
-core production       <= +1,500, or paid for by larger plugin deletion
-tests                 <= +1,000
-total                 <= +2,000
-
-stretch:
-plugin production     <= -2,500
-core production       <= +1,200
-total                 <= 0
-```
-
-Minimum remaining cleanup:
-
-```text
-plugin production     needs 260 more net deleted lines
-total                 needs 775 more net deleted lines
-core production       still +1,876 over standalone budget, unless paid down by plugin deletion
-```
-
-Comment-only deletion does not count as cleanup. The previous budget pass was
-too generous because it included restored QQBot explanatory comments; this
-document tracks executable/docs/test code movement only.
-
-Re-measure after each cleanup wave:
-
-```sh
-base=$(git merge-base HEAD origin/main)
-git diff --shortstat "$base"
-git diff --numstat "$base" -- src/channels/message-access src/plugin-sdk extensions | sort -nr -k1 | head -n 80
-pnpm lint:extensions:no-deprecated-channel-access
-```
-
-## Diagnosis
-
-The first pass added the shared ingress kernel, then left too much plugin-local
-authorization beside it:
-
-```text
-platform facts
-  -> shared ingress state and decision
-  -> plugin-local DTO or legacy projection
-  -> plugin-local if/else ladder
-```
-
-That duplicates the model. Core production grew by about 3,376 lines, while
-bundled plugin production is 1,240 lines smaller. That is better than the first
-pass, but it is not inside the minimum budget. The fix remains deletion-first:
-
-- delete plugin DTOs that only rename ingress fields
-- delete tests that only assert wrapper shape
-- add core helpers only when the same patch deletes bundled plugin code
-- keep old SDK compatibility in SDK/core shims only
-- repack core after wrapper deletion exposes the stable shape
-
-## Hotspots
-
-Positive bundled production files that still need to shrink:
-
-```text
-extensions/telegram/src/ingress.ts                        +126
-extensions/discord/src/monitor/dm-command-auth.ts         +101
-extensions/signal/src/monitor/access-policy.ts             +92
-extensions/feishu/src/policy.ts                            +85
-extensions/slack/src/monitor/auth.ts                       +64
-extensions/googlechat/src/monitor-access.ts                +59
-extensions/nextcloud-talk/src/inbound.ts                   +51
-extensions/matrix/src/matrix/monitor/access-state.ts       +49
-extensions/irc/src/inbound.ts                              +44
-extensions/imessage/src/monitor/inbound-processing.ts      +36
-extensions/qa-channel/src/inbound.ts                       +34
-extensions/qqbot/src/bridge/sdk-adapter.ts                 +33
-extensions/tlon/src/monitor/utils.ts                       +30
-extensions/twitch/src/access-control.ts                    +22
-extensions/qqbot/src/engine/commands/slash-command-handler.ts +20
-extensions/telegram/src/bot-handlers.runtime.ts            +19
-```
-
-The branch is not inside the minimum budget yet. The remaining review-relevant
-work should delete repeated authorization flow, turn scaffolding, or wrapper
-tests before adding another core abstraction.
-
-## Current Code Read
-
-The healthy core seam already exists in `src/channels/message-access/runtime.ts`:
-it owns identity adapters, effective allowlists, pairing-store reads, route
-descriptors, command/event presets, access groups, and the final resolved
-`ResolvedChannelMessageIngress` projection.
-
-The remaining growth is mostly plugin glue layered on top of that seam:
-
-- `extensions/telegram/src/ingress.ts` wraps core decisions in Telegram-specific
-  command/event helpers, then call sites still pass precomputed normalized
-  allowlists and owner lists.
-- `extensions/discord/src/monitor/dm-command-auth.ts`,
-  `extensions/feishu/src/policy.ts`, `extensions/googlechat/src/monitor-access.ts`,
-  and `extensions/matrix/src/matrix/monitor/access-state.ts` still keep
-  local policy DTOs or legacy decision names beside ingress.
-- `extensions/signal/src/monitor/access-policy.ts` correctly keeps Signal
-  identity normalization and pairing replies local, but still has a wrapper
-  seam that should collapse into direct ingress consumption.
-- `extensions/nextcloud-talk/src/inbound.ts`, `extensions/irc/src/inbound.ts`,
-  `extensions/qa-channel/src/inbound.ts`, `extensions/zalo/src/monitor.ts`, and
-  `extensions/zalouser/src/monitor.ts` still repeat route/envelope/turn
-  assembly that can move to shared turn helpers outside the ingress kernel.
-
-Conclusion: moving more code into core is only useful if it deletes these
-plugin wrapper layers in the same patch. Adding another abstraction while
-leaving wrapper returns in place repeats the mistake.
-
-## Boundary
-
-Core owns generic policy:
-
-- allowlist normalization and matching
-- access-group expansion and diagnostics
-- pairing-store DM allowlist reads
-- route, sender, command, event, and activation gates
-- admission mapping: dispatch, drop, skip, observe, pairing
-- redacted state, decisions, diagnostics, and SDK compatibility projections
-- reusable generic descriptors for identity, route, command, event, activation,
-  and outcomes
-
-Plugins own transport facts and side effects:
-
-- webhook/socket/request authenticity
-- platform identity extraction and API lookups
-- channel-specific policy defaults
-- pairing challenge delivery, replies, acks, reactions, typing, media, history,
-  setup, doctor, status, logs, and user-facing copy
-
-Core must stay channel-agnostic: no Discord, Slack, Telegram, Matrix, room,
-guild, space, API client, or plugin-specific default in
-`src/channels/message-access`.
-
-## Acceptance Rule
-
-Every new core helper must delete bundled plugin production code immediately.
-
-```text
-one bundled caller        reject; keep plugin-local
-two bundled callers       accept only if plugin production LOC drops
-three or more callers     plugin deletion must be at least 2x new core LOC
-compatibility-only helper SDK/core shim only; never bundled hot paths
-```
-
-Stop and redesign if:
-
-- plugin production LOC increases
-- tests grow faster than production shrinks
-- a bundled hot path returns a DTO that only renames `ResolvedChannelMessageIngress`
-- a core helper needs a channel id, platform object, API client, or
-  channel-specific default
-
-## Work Packages
-
-1. Freeze the budget.
-   Put LOC in the PR, keep deprecated-ingress lint green, and include before/after
-   LOC in cleanup commits.
-
-2. Delete thin DTO seams.
-   Replace plugin-local wrapper returns with `ResolvedChannelMessageIngress`,
-   `senderAccess`, `commandAccess`, `routeAccess`, or `ingress` directly. Start
-   with QQBot, Telegram, Slack, Discord, Signal, Feishu, Matrix, iMessage, and
-   Tlon. Delete wrapper-shape tests; keep behavior tests.
-
-3. Add outcome classification only with deletions.
-   A generic classifier may expose `dispatch`, `pairing-required`,
-   `skip-activation`, `drop-command`, `drop-route`, `drop-sender`, and
-   `drop-ingress`. It must derive from the decision graph, not reason strings,
-   and migrate at least three plugins in the same patch.
-
-4. Add route descriptor builders only with deletions.
-   Generic route target and route sender helpers are acceptable only if they
-   immediately shrink route-heavy plugins: Google Chat, IRC, Microsoft Teams,
-   Nextcloud Talk, Mattermost, Slack, Zalo, and Zalo Personal.
-
-5. Add command/event presets only with deletions.
-   Centralize text-command, native-command, callback, and origin-subject shapes.
-   Command consumers must default to unauthorized when no command gate ran;
-   events must not start pairing.
-
-6. Add identity presets only where they remove boilerplate.
-   Stable-id, stable-id-plus-aliases, phone/e164, and multi-identifier helpers
-   are allowed when raw values enter only adapter input and redacted state keeps
-   opaque ids/counts.
-
-7. Share authorized turn assembly.
-   Outside the ingress kernel, remove repeated route/envelope/context/reply
-   scaffolding from QA Channel, IRC, Nextcloud Talk, Zalo, and Zalo Personal.
-   Core may own route/session/envelope/dispatch sequencing; plugins keep
-   delivery and channel-specific context.
-
-8. Quarantine compatibility.
-   Deprecated SDK helpers stay source-compatible, but bundled hot paths must not
-   import deprecated ingress or command-auth facades. Compatibility tests should
-   use fake third-party plugins, not bundled-plugin internals.
-
-9. Repack core.
-   After wrapper deletion, collapse one-use modules, remove unused exports, move
-   compatibility projection out of hot paths, and keep focused tests for identity,
-   route, command/event, activation, access groups, and compatibility shims.
-
-## Deletion Waves
-
-Run these in order. Each wave must lower bundled production LOC.
-
-1. Wrapper collapse, expected plugin delta: -400 to -600.
-   Replace plugin-local `resolveXAccess`, `resolveXCommandAccess`, and
-   `accessFromIngress` result types with direct reads from
-   `ResolvedChannelMessageIngress`. First targets: Discord DM command auth,
-   Feishu policy, Matrix access state, Telegram ingress, Signal access policy,
-   QQBot SDK adapter.
-
-2. Shared outcome helpers, expected plugin delta: -200 to -350.
-   Add one generic classifier only if it deletes repeated
-   `shouldBlockControlCommand`, pairing, activation skip, route block, and sender
-   block ladders across at least three plugins.
-
-3. Route descriptor builders, expected plugin delta: -200 to -350.
-   Move repeated route target and route sender descriptor assembly into core
-   helpers. First targets: Google Chat, IRC, Microsoft Teams, Nextcloud Talk,
-   Mattermost, Slack, Zalo, Zalo Personal.
-
-4. Turn assembly sharing, expected plugin delta: -250 to -450.
-   Use common route/session/envelope/dispatch sequencing for simple inbound
-   plugins. First targets: QA Channel, IRC, Nextcloud Talk, Zalo, Zalo Personal.
-
-5. Core repack, expected core delta: -300 to -700.
-   After plugins consume runtime projections directly, delete one-use modules,
-   merge tiny files back into `runtime.ts` or focused siblings, and keep SDK
-   compatibility files separate from bundled hot paths.
-
-6. Test pruning, expected test delta: -300 to -600.
-   Delete tests that only assert removed wrapper shapes. Keep behavior tests for
-   command denial, group fallback, origin-subject matching, activation skip,
-   access groups, pairing, and redaction.
-
-Expected minimum landing shape after these waves:
-
-```text
-plugin production     <= -1,500
-core production       about +1,800 to +2,200 before final repack
-tests                 <= +500
-total                 <= +2,000
-```
-
-## Do Not Move
-
-Do not move platform config defaults, setup UX, doctor/fix copy, API lookups,
-Slack owner-presence checks, Matrix alias/verification handling, Telegram
-callback parsing, command syntax parsing, native command registration, reaction
-payload parsing, pairing replies, command replies, acks, typing, media, history,
-or logs.
-
-## Verification
-
-Targeted local loop:
-
-```sh
-pnpm lint:extensions:no-deprecated-channel-access
-pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.ts src/plugin-sdk/access-groups.test.ts
-pnpm test extensions/<changed-plugin>/src/...
-pnpm plugin-sdk:api:check
-pnpm config:docs:check
-pnpm check:docs
-git diff --check
-```
-
-Use Testbox for broad changed gates/full-suite proof once the LOC trend is
-inside budget.
-
-Each work package records:
-
-- before/after LOC by category
-- deleted plugin wrappers
-- new core helper LOC, if any
-- targeted tests run
-- remaining hotspot list
-
-## Exit Criteria
-
-- bundled production imports no deprecated channel-access or command-auth facades
-- compatibility code is isolated to SDK/core seams
-- bundled plugins consume ingress projections or generic outcomes directly
-- plugin production LOC is at least 1,500 net negative against `origin/main`
-- core production LOC is `<= +1,500`, or any excess is paid for while total
-  stays `<= +2,000`
-- representative tests cover redaction, route, command/event, activation,
-  access-group, and channel-specific fallback behavior

package/docs/reference/AGENTS.default.md

@@ -1,131 +0,0 @@
----
-summary: "Default FengMing agent instructions and skills roster for the personal assistant setup"
-title: "Default AGENTS.md"
-read_when:
-  - Starting a new FengMing agent session
-  - Enabling or auditing default skills
----
-
-## First run (recommended)
-
-FengMing uses a dedicated workspace directory for the agent. Default: `~/.fengming/workspace` (configurable via `agents.defaults.workspace`).
-
-1. Create the workspace (if it doesn't already exist):
-
-```bash
-mkdir -p ~/.fengming/workspace
-```
-
-2. Copy the default workspace templates into the workspace:
-
-```bash
-cp docs/reference/templates/AGENTS.md ~/.fengming/workspace/AGENTS.md
-cp docs/reference/templates/SOUL.md ~/.fengming/workspace/SOUL.md
-cp docs/reference/templates/TOOLS.md ~/.fengming/workspace/TOOLS.md
-```
-
-3. Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
-
-```bash
-cp docs/reference/AGENTS.default.md ~/.fengming/workspace/AGENTS.md
-```
-
-4. Optional: choose a different workspace by setting `agents.defaults.workspace` (supports `~`):
-
-```json5
-{
-  agents: { defaults: { workspace: "~/.fengming/workspace" } },
-}
-```
-
-## Safety defaults
-
-- Don't dump directories or secrets into chat.
-- Don't run destructive commands unless explicitly asked.
-- Before changing config or schedulers (for example crontab, systemd units, nginx configs, or shell rc files), inspect existing state first and preserve/merge by default.
-- Don't send partial/streaming replies to external messaging surfaces (only final replies).
-
-## Session start (required)
-
-- Read `SOUL.md`, `USER.md`, and today+yesterday in `memory/`.
-- Read `MEMORY.md` when present.
-- Do it before responding.
-
-## Soul (required)
-
-- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
-- If you change `SOUL.md`, tell the user.
-- You are a fresh instance each session; continuity lives in these files.
-
-## Shared spaces (recommended)
-
-- You're not the user's voice; be careful in group chats or public channels.
-- Don't share private data, contact info, or internal notes.
-
-## Memory system (recommended)
-
-- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
-- Long-term memory: `MEMORY.md` for durable facts, preferences, and decisions.
-- Lowercase `memory.md` is legacy repair input only; do not keep both root files on purpose.
-- On session start, read today + yesterday + `MEMORY.md` when present.
-- Before writing memory files, read them first; write only concrete updates, never empty placeholders.
-- Capture: decisions, preferences, constraints, open loops.
-- Avoid secrets unless explicitly requested.
-
-## Tools and skills
-
-- Tools live in skills; follow each skill's `SKILL.md` when you need it.
-- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
-
-## Backup tip (recommended)
-
-If you treat this workspace as Clawd's "memory", make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
-
-```bash
-cd ~/.fengming/workspace
-git init
-git add AGENTS.md
-git commit -m "Add Clawd workspace"
-# Optional: add a private remote + push
-```
-
-## What FengMing does
-
-- Runs WhatsApp gateway + embedded FengMing agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
-- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `fengming` CLI via its bundled binary.
-- Direct chats collapse into the agent's `main` session by default; groups stay isolated as `agent:<agentId>:<channel>:group:<id>` (rooms/channels: `agent:<agentId>:<channel>:channel:<id>`); heartbeats keep background tasks alive.
-
-## Core skills (enable in Settings → Skills)
-
-- **mcporter** - Tool server runtime/CLI for managing external skill backends.
-- **Peekaboo** - Fast macOS screenshots with optional AI vision analysis.
-- **camsnap** - Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
-- **oracle** - OpenAI-ready agent CLI with session replay and browser control.
-- **eightctl** - Control your sleep, from the terminal.
-- **imsg** - Send, read, stream iMessage & SMS.
-- **wacli** - WhatsApp CLI: sync, search, send.
-- **discord** - Discord actions: react, stickers, polls. Use `user:<id>` or `channel:<id>` targets (bare numeric ids are ambiguous).
-- **gog** - Google Suite CLI: Gmail, Calendar, Drive, Contacts.
-- **spotify-player** - Terminal Spotify client to search/queue/control playback.
-- **sag** - ElevenLabs speech with mac-style say UX; streams to speakers by default.
-- **Sonos CLI** - Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
-- **blucli** - Play, group, and automate BluOS players from scripts.
-- **OpenHue CLI** - Philips Hue lighting control for scenes and automations.
-- **OpenAI Whisper** - Local speech-to-text for quick dictation and voicemail transcripts.
-- **Gemini CLI** - Google Gemini models from the terminal for fast Q&A.
-- **agent-tools** - Utility toolkit for automations and helper scripts.
-
-## Usage notes
-
-- Prefer the `fengming` CLI for scripting; mac app handles permissions.
-- Run installs from the Skills tab; it hides the button if a binary is already present.
-- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
-- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don't rely on safe-area insets.
-- For browser-driven verification, use `fengming browser` (tabs/status/screenshot) with the FengMing-managed Chrome profile.
-- For DOM inspection, use `fengming browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
-- For interactions, use `fengming browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).
-
-## Related
-
-- [Agent workspace](/concepts/agent-workspace)
-- [Agent runtime](/concepts/agent)