feishu-codex-connector 0.1.6

package/docs/COMMAND_COMPLETION_SPEC.md

@@ -0,0 +1,92 @@
+# Command Completion Spec
+
+## Decisions
+
+- `workspace` means a local working directory.
+- `session` means a Codex thread for a Feishu/Lark scope in a workspace under a compatible policy.
+- Do not add a `project` concept.
+- Do not force one group to bind permanently to one workspace.
+- Do not add Codex project import in this milestone.
+- Use `/new group [name]` for new Feishu/Lark group creation.
+
+## CLI Commands
+
+### Service lifecycle
+
+`feishu-codex start|stop|restart|status|unregister --profile <name>` must manage a real OS service where supported:
+
+- macOS: launchd user agent.
+- Linux: systemd user unit.
+- Windows: Task Scheduler.
+
+`status` must report whether the service definition exists and whether the service is currently running.
+
+### Process management
+
+`feishu-codex ps` must list registered runtime processes after pruning dead PIDs.
+
+`feishu-codex kill <id|pid>` must send SIGTERM to a registered process, or a numeric PID when it is registered.
+
+## Chat Commands
+
+### Sessions
+
+- `/new` and `/reset` clear the current scope session and stop any active run.
+- `/resume` lists recent compatible sessions for the current scope and workspace.
+- `/resume use <nonce>` restores the selected session when the nonce is valid.
+
+### Group creation
+
+- `/new group [name]` creates a new Feishu/Lark group chat through the bot account.
+- The new group inherits the source scope workspace when one is configured.
+- The bridge sends a welcome message in the new group and an acknowledgement in the source chat.
+
+### Workspaces
+
+- `/cd <path>` switches the current scope to an absolute workspace path.
+- `/ws save <name>` saves the current scope workspace as an alias.
+- `/ws add <name> <path>` saves a specific absolute path as an alias.
+- `/ws use <name>` switches to a saved alias.
+- `/ws remove <name>` removes a saved alias.
+
+### Configuration
+
+- `/config` returns an interactive configuration card.
+- `/config show` returns a read-only configuration summary.
+- `/config submit` applies a card form submission after admin re-authorization.
+
+### Timeout
+
+- `/timeout <minutes|off|default>` changes the current scope idle timeout.
+- Global default timeout belongs in `/config`.
+- `/new` clears the current scope override by clearing the session record.
+
+### Access control
+
+- `/invite group` only works in group or topic scopes.
+- `/invite user @name` and `/invite admin @name` require at least one real user mention.
+- `/invite all group` lists bot-joined chats through the channel gateway and adds them to `allowedChats`.
+- `/remove user @name`, `/remove admin @name`, and `/remove group` mirror invite validation.
+
+### Diagnostics
+
+- `/doctor` returns a concise low-sensitive status.
+- `/doctor detail` returns expanded diagnostics.
+- `feishu-codex doctor --json` returns machine-readable diagnostics.
+
+## Callback Security
+
+All state-changing command-card buttons must include a signed callback token with:
+
+- command
+- scope
+- chat
+- operator
+- TTL
+- nonce
+
+The runtime must verify the token and re-run access control before executing the command.
+
+## Real E2E Checks
+
+Document comments and generic file attachments require real Feishu/Lark tests after permissions are granted. The code path must reject missing permissions clearly and the docs must include a repeatable checklist.

package/docs/FEATURE_PARITY_SPEC.md

@@ -0,0 +1,104 @@
+# Feature Parity Specification
+
+This document specifies the connector features needed to align the Codex-only connector with the core user-facing behavior of `lark-coding-agent-bridge` while keeping this repository's smaller architecture.
+
+## 1. Streaming Run Cards
+
+The bridge must send one run card per Codex turn and update that same card for text, tool calls, usage, terminal state, and stop actions.
+
+Required behavior:
+
+- The initial card is created before or immediately after the Codex run starts.
+- Text deltas append to the current output.
+- Tool start/end events render as distinct tool blocks.
+- Repeated updates are throttled to avoid Feishu/Lark rate limits.
+- Terminal events flush immediately.
+- The Stop button is signed, scoped to the active run, and replay protected.
+- Card rendering must cap per-tool and full-card content to avoid platform size errors.
+- The final card must not leave an older `Codex running` card behind.
+
+Acceptance criteria:
+
+- A fast run produces one sent card and subsequent updates patch that card.
+- A run with text and tools shows both.
+- Stop only affects the matching scope/run.
+
+## 2. Document Comment Runs
+
+The bridge must handle Feishu/Lark cloud document comment mentions as independent Codex sessions.
+
+Required behavior:
+
+- Subscribe to and normalize comment events from the long-connection channel.
+- Ignore comment events where the bot was not mentioned.
+- Support `doc`, `docx`, `sheet`, and generic file comments first.
+- Fetch the comment thread context, including the triggering reply text, quote text when available, and whole-document vs inline-comment flag.
+- Use a stable comment-thread scope so every document comment thread has its own Codex thread.
+- Run Codex with the same workspace and policy machinery used by IM messages.
+- Reply to the same comment thread with plain text.
+- Do not ask Codex to call comment APIs itself; the bridge owns comment replies.
+
+Acceptance criteria:
+
+- A normalized comment mention starts a Codex run using a `comment:*` scope.
+- The final reply is posted as a plain comment reply.
+- The comment scope can resume its previous Codex thread when policy/workspace match.
+
+## 3. Short-Window Message Batching
+
+The bridge must merge messages sent close together in the same scope before creating a Codex turn.
+
+Required behavior:
+
+- Non-command messages enter a per-scope pending queue.
+- The queue flushes after a quiet window, defaulting to the profile `preferences.debounceMs`.
+- While a scope has an active run, ordinary messages accumulate but do not start a new run.
+- When the active run finishes, queued messages wait for a fresh quiet window and then run as a combined prompt.
+- Commands bypass the queue.
+- Commands that change session/workspace state cancel pending ordinary messages for that scope.
+
+Acceptance criteria:
+
+- Two quick messages in one scope produce one Codex run.
+- Messages sent during a run merge into the next run.
+- `/cd`, `/ws use`, `/new`, `/reset`, and `/stop` are handled immediately.
+
+## 4. Image And File Attachments
+
+The bridge must download user-sent Feishu/Lark image and file resources into a profile-local media cache and pass accepted attachments to Codex.
+
+Required behavior:
+
+- Normalize resources from incoming SDK messages.
+- Download message resources with the message-resource API, not the bot-upload file API.
+- Store downloads under `~/.feishu-codex/profiles/<profile>/media`.
+- Use content hashes for dedupe and stable local paths.
+- Apply attachment policy for max count, total bytes, image bytes, and file bytes.
+- Pass accepted image paths to Codex `imagePaths`.
+- Describe accepted file paths in the structured prompt so Codex can read them locally.
+- Skip or reject unsupported kinds with a user-visible policy note when required.
+
+Acceptance criteria:
+
+- Image messages produce accepted image attachments and run input image paths.
+- File messages produce local cached paths in the prompt.
+- Rejected required attachments reject the run before Codex starts.
+
+## 5. Interactive Command Cards
+
+The bridge must return clickable cards for high-frequency commands.
+
+Required behavior:
+
+- `/help` returns a card with shortcut buttons for status, workspace list, and new session.
+- `/status` returns a card with profile, scope, workspace, session, queue, auth, and permission details plus useful action buttons.
+- `/ws list` returns a card showing current workspace and saved aliases.
+- Workspace rows include buttons for `ws.use` and `ws.remove`.
+- Card action payloads dispatch through the same command router as slash commands.
+- Card actions must resolve the correct chat/topic scope and enforce access checks.
+
+Acceptance criteria:
+
+- Clicking `/ws list` "use" switches the workspace for the same scope.
+- Clicking `/status` "new session" resets the same scope.
+- Unauthorized users cannot execute admin card actions.

package/docs/FEISHU_PERMISSIONS.md

@@ -0,0 +1,24 @@
+# Feishu/Lark App Permission Matrix
+
+V1 uses a personal local runtime and the Feishu/Lark long-connection channel. Exact scope names vary between Feishu and Lark tenants, but the app needs the following capability groups enabled before production use.
+
+| Capability | Required for | Notes |
+|---|---|---|
+| IM message receive | Private, group, and topic input | Required for ordinary Codex tasks and slash commands. |
+| IM message send/reply/update | Rich run cards, markdown fallback, status/help replies | Card update permission is needed for streaming run cards. |
+| Card callbacks | Stop button and interactive configuration/status cards | Callback payloads are signed and nonce-protected by the bridge. |
+| Mention metadata | Group mention policy and `/invite user @name` parsing | Mention-all must not count as a bot trigger. |
+| Chat metadata | Group/topic scope resolution and diagnostics | Used to distinguish private, group, and topic contexts. |
+| Chat create/member management | `/new group [name]` and `/invite all group` discovery | Requires the app to create group chats and invite the requesting user. |
+| File/media download | Image and file attachments | Attachment policy enforces count, size, and MIME limits before Codex sees files. |
+| Document comment read/reply | Document comment mention flow | Replies should be plain text by default. |
+| Bot info / app owner lookup | Owner/admin access control and `/status` | If owner refresh fails, access must not widen. |
+| Optional contact lookup | Human-readable diagnostics and invite resolution | Never required for raw Codex execution. |
+
+Security defaults:
+
+- Owner-only use is the default.
+- Groups require a real bot mention by default.
+- `bot-only` Feishu/Lark CLI identity is the default.
+- `user-default` CLI identity is denied in group chats unless the owner explicitly enables it.
+- Codex sandbox permissions are controlled by the profile permissions, regardless of Codex auth mode.