feishu-codex-connector 0.1.6

package/docs/SPEC.md

@@ -0,0 +1,825 @@
+# Feishu Codex Connector Functional Specification
+
+## 1. Scope
+
+This specification defines the first implementation target for `feishu-codex-connector`: a Codex-only connector controlled from Feishu/Lark.
+
+The first version must feel complete for a single owner, a small team, and a project group:
+
+- Start and manage the bridge locally or as a background service.
+- Bind a Feishu/Lark app.
+- Receive private, group, topic, card, and document-comment inputs.
+- Run Codex in a selected workspace.
+- Stream output back to the user through rich run cards by default.
+- Preserve session continuity.
+- Enforce access, workspace, sandbox, callback, and attachment policies.
+- Support Codex API key authentication without requiring interactive Codex login on the host.
+- Expose profile-local Feishu/Lark CLI identity to Codex when configured.
+
+## 2. Product Personas
+
+### 2.1 Owner
+
+The person who creates or owns the Feishu/Lark app. The owner can:
+
+- Use the bot in private chats and groups.
+- Manage access lists.
+- Change configuration.
+- Run diagnostics.
+- Stop or restart connector processes.
+
+### 2.2 Admin
+
+A trusted maintainer added by the owner. An admin can:
+
+- Use private chat.
+- Use the bot in any group where access policy permits admin bypass.
+- Manage workspaces and access.
+- Run diagnostics and lifecycle commands.
+
+### 2.3 Allowed User
+
+A user explicitly allowed to use the bot in private chat or in an allowed group. An allowed user can:
+
+- Send ordinary Codex tasks.
+- Stop their current run.
+- Reset or resume their own scope.
+
+### 2.4 Group Member
+
+A member of an allowed group. They can use the bot only according to group mention policy.
+
+## 3. Profile and Runtime Management
+
+### V1 Runtime Boundary
+
+V1 primary mode is personal local mode.
+
+Required behavior:
+
+- The bridge runs on the owner's workstation or personal development host.
+- Codex edits the selected local workspace directly under the configured sandbox.
+- Owner-only usage is the safest default, while allowed users/groups are opt-in.
+- Team-managed worktrees, containers, PR automation, and remote multi-tenant hosting are future modes.
+- App-server execution is not required for V1, but the runner interface must not block adding it later.
+
+### 3.1 Profile Create
+
+Command:
+
+```bash
+feishu-codex profile create <name>
+```
+
+Required behavior:
+
+- Prompt for tenant: `feishu` or `lark`.
+- Prompt for app ID and app secret, or run an app-binding wizard if available.
+- Detect Codex SDK/runtime availability.
+- Prompt for Codex auth mode: `api-key`, `codex-home`, or `inherit-user`.
+- For `api-key`, store the API key as a secret reference and validate it with a low-risk availability check.
+- Create a profile-local Codex home unless `inherit-user` is explicitly selected.
+- Initialize profile-local Feishu/Lark CLI identity settings with `bot-only` as the default.
+- Create profile directory under `~/.feishu-codex/profiles/<name>`.
+- Create local state files with secure permissions.
+- Store app secret using configured secret storage.
+- Optionally set an initial workspace.
+
+Acceptance criteria:
+
+- New profile appears in `profile list`.
+- App secret is not written as cleartext in normal config.
+- Codex API key is not written as cleartext in normal config.
+- `feishu-codex run --profile <name>` can start from the profile.
+
+### 3.2 Profile Use/List/Remove/Export
+
+Commands:
+
+```bash
+feishu-codex profile list
+feishu-codex profile use <name>
+feishu-codex profile remove <name>
+feishu-codex profile export <name>
+```
+
+Required behavior:
+
+- `list` shows active profile, tenant, app ID suffix, workspace status, backend, Codex auth mode, and Feishu/Lark CLI identity preset.
+- `use` changes default profile.
+- `remove` archives local state by default.
+- `remove --purge --yes` permanently deletes profile state.
+- `export` redacts secrets unless `--include-secrets --yes` is provided.
+
+### 3.3 Foreground Run
+
+Command:
+
+```bash
+feishu-codex run [--profile <name>] [--workspace <path>]
+```
+
+Required behavior:
+
+- Resolve profile.
+- Run preflight checks.
+- Acquire profile and app locks.
+- Connect Feishu/Lark channel.
+- Register process.
+- Listen until signal or `/exit`.
+- Flush stores on shutdown.
+
+### 3.4 Background Service
+
+Commands:
+
+```bash
+feishu-codex start [--profile <name>]
+feishu-codex stop [--profile <name>]
+feishu-codex restart [--profile <name>]
+feishu-codex status [--profile <name>]
+feishu-codex unregister [--profile <name>]
+```
+
+Required behavior:
+
+- macOS: launchd user agent.
+- Linux: systemd user service.
+- Windows: Task Scheduler task.
+- Logs written under profile logs directory.
+- Service commands must not depend on temporary `npx` paths.
+
+## 4. Feishu/Lark Event Handling
+
+### 4.1 Private Message
+
+Required behavior:
+
+- Accept message when actor is owner, admin, or allowed user.
+- Do not require bot mention.
+- Scope ID is private chat scope.
+- Ordinary messages enter the run queue.
+- Slash commands are handled immediately.
+
+Acceptance criteria:
+
+- Unauthorized private sender gets no Codex run.
+- Authorized sender receives a streamed response.
+
+### 4.2 Group Message
+
+Required behavior:
+
+- Accept message when group is allowed, or actor is owner/admin.
+- If `requireMentionInGroup` is true, ignore messages without a real bot mention.
+- Ignore mention-all as a trigger.
+- Scope ID is group chat scope.
+
+Acceptance criteria:
+
+- Allowed group + real mention triggers run.
+- Allowed group + no mention does not trigger run when mention is required.
+- Disallowed group does not run Codex.
+
+### 4.3 Topic Group Message
+
+Required behavior:
+
+- Resolve topic/thread ID.
+- Scope ID includes chat ID and topic/thread ID.
+- Replies are posted back into the same topic when possible.
+- Each topic has independent workspace, queue, active run, and session state.
+
+### 4.4 Quoted Message Context
+
+Required behavior:
+
+- Detect when a message quotes another message.
+- Fetch quoted message content when permitted.
+- Deduplicate quote targets across a batched run.
+- Include quote context in structured prompt.
+- Avoid fetching quote targets that are already part of the current batch.
+
+### 4.5 Card Action
+
+Required behavior:
+
+- Resolve card action scope.
+- Verify actor access before executing.
+- Dispatch built-in command callbacks.
+- Forward signed agent callbacks into the scope queue as synthetic messages.
+- Include CardKit form values when present.
+- Reject unsigned sensitive callbacks.
+
+Acceptance criteria:
+
+- Stop button stops only the matching active run.
+- Replay of the same callback nonce is rejected.
+- Callback from a different operator is rejected.
+
+### 4.6 Document Comment Mention
+
+Required behavior:
+
+- React only when the bot is mentioned.
+- Support configured document/file types for comment retrieval.
+- Fetch comment text, quote, and context.
+- Build a comment-specific prompt.
+- Run Codex using document-level session continuity.
+- Post plain-text reply into the same comment thread.
+- Skip self-replies.
+
+Acceptance criteria:
+
+- Mention in supported comment triggers one reply.
+- Reply does not contain raw Markdown formatting unless user explicitly requested literal Markdown.
+- Concurrent comments on the same document do not corrupt the document-level session.
+
+## 5. Built-in Commands
+
+### 5.1 `/help`
+
+Shows available commands and current agent/backend label.
+
+### 5.2 `/status`
+
+Shows:
+
+- profile
+- tenant
+- bot name if known
+- current scope
+- chat mode
+- selected workspace
+- Codex backend
+- Codex auth mode
+- Feishu/Lark CLI identity preset
+- sandbox/access mode
+- current thread ID or empty state
+- active run status
+- queue snapshot
+- access status
+- owner refresh status
+
+### 5.3 `/new` and `/reset`
+
+Required behavior:
+
+- Stop current run if active.
+- Archive or clear active Codex thread for the current scope.
+- Preserve non-session preferences such as idle timeout if configured.
+
+### 5.4 `/cd <path>`
+
+Required behavior:
+
+- Admin-only.
+- Accept absolute paths and `~/...`.
+- Reject relative paths.
+- Resolve realpath.
+- Reject dangerous broad directories.
+- Stop current run.
+- Set current scope workspace.
+- Reset current scope session.
+
+### 5.5 `/ws`
+
+Subcommands:
+
+```text
+/ws list
+/ws save <name>
+/ws add <name> <path>
+/ws use <name>
+/ws remove <name>
+```
+
+Required behavior:
+
+- Admin-only.
+- Workspace aliases are scoped by profile, owner, and chat scope.
+- Legacy global aliases may be read if migration support is enabled.
+- `use` validates the target path before switching.
+- `add` validates the target path before saving.
+
+### 5.5.1 `/new group`
+
+Required behavior:
+
+- Owner/admin-only.
+- Create a new Feishu/Lark group chat.
+- Invite the requesting user.
+- Inherit the source scope workspace when configured.
+- Send a welcome message to the new group.
+- Reply to the source scope with the creation result.
+
+### 5.6 `/resume`
+
+Required behavior:
+
+- Show recent compatible Codex threads for current workspace and policy.
+- In group chats, avoid exposing detailed history unless configured.
+- Issue short-lived nonces for resume candidates.
+- `/resume use <nonce>` restores the selected thread only if scope, cwd, and policy fingerprint match.
+
+### 5.7 `/stop`
+
+Required behavior:
+
+- Stop current scope run.
+- Do not send an extra reply if the run card can update itself.
+- Admins may stop another scope by explicit target.
+
+### 5.8 `/timeout`
+
+Required behavior:
+
+- Show current idle watchdog setting.
+- Set per-scope timeout in minutes.
+- `off` disables per-scope watchdog.
+- `default` clears per-scope override.
+- Clamp allowed values to a safe range.
+
+### 5.9 `/config`
+
+Required behavior:
+
+- Admin-only.
+- Render interactive configuration card.
+- Support reply mode, show tool calls, max concurrency, mention policy, access mode, network access, idle timeout, Codex auth mode, and Feishu/Lark CLI identity preset.
+- Validate form values before saving.
+- Restart or reconnect when changes require it.
+
+### 5.10 `/invite` and `/remove`
+
+Required behavior:
+
+- Admin-only.
+- Add/remove allowed users, groups, and admins.
+- Parse mentioned users from structured mentions.
+- `/invite group` allows current group.
+- `/invite all group` may add all known groups if the platform API permits.
+
+### 5.11 `/doctor`
+
+Required behavior:
+
+- Admin-only.
+- Rate limited per user.
+- Checks workspace, access, policy, queue, Codex availability, and echo run.
+- In group chats, send sensitive diagnostic details privately to the operator.
+
+### 5.12 `/ps`, `/exit`, `/reconnect`
+
+Required behavior:
+
+- Admin-only.
+- `/ps` lists registered connector processes.
+- `/exit <id|#>` stops selected process.
+- `/reconnect` pauses new runs, stops or waits for active runs, reloads config, reconnects channel.
+
+## 6. Codex Execution
+
+### 6.1 Backend Selection
+
+Profile field:
+
+```json
+{
+  "codex": {
+    "backend": "sdk"
+  }
+}
+```
+
+Supported values:
+
+| Backend | V1 status | Purpose |
+|---|---|---|
+| `sdk` | Required | Normal execution through Codex TypeScript SDK. |
+| `app-server` | Reserved | Advanced lifecycle and approval support in V2. Not used for V1 normal execution. |
+| `exec-json` | Diagnostic fallback | Compatibility fallback for local troubleshooting, not the product default. |
+
+### 6.2 Run Input
+
+Every Codex run receives:
+
+- run ID
+- prompt
+- cwd realpath
+- optional thread ID
+- sandbox mode
+- network access setting
+- image paths
+- profile environment
+- Codex auth material resolved from the profile secret provider
+- Feishu/Lark CLI identity environment when enabled
+- stop signal
+- idle timeout
+
+### 6.3 Run Output
+
+Runner output must be translated into:
+
+- thread started/resumed
+- text delta or final text
+- tool start
+- tool result
+- usage
+- approval request if backend supports it
+- done
+- error
+
+### 6.4 Stop Semantics
+
+Required behavior:
+
+- `/stop` marks the run interrupted.
+- SDK runner uses abort signal first.
+- Process fallback terminates the child process tree when available.
+- Stop has a grace period before force kill.
+- Card terminal state becomes interrupted.
+
+### 6.5 Thread Continuity
+
+Required behavior:
+
+- Save Codex thread ID after first successful thread event.
+- Resume only when scope, cwd, and policy fingerprint match.
+- Reset thread on `/new`, `/cd`, or incompatible policy change.
+
+### 6.6 Codex Authentication
+
+Profile field:
+
+```json
+{
+  "codex": {
+    "backend": "sdk",
+    "auth": {
+      "mode": "api-key",
+      "apiKey": { "source": "keystore", "id": "openai-api-key-default" }
+    },
+    "codexHome": "~/.feishu-codex/profiles/default/codex-home",
+    "inheritUserCodexHome": false
+  }
+}
+```
+
+Supported auth modes:
+
+| Mode | V1 status | Required behavior |
+|---|---|---|
+| `api-key` | Required | Resolve a profile secret and pass it to the Codex SDK for the run. |
+| `codex-home` | Required | Use a profile-local Codex home containing local Codex login/config state. |
+| `inherit-user` | Optional | Reuse the host user's Codex login only after explicit owner configuration. |
+
+Acceptance criteria:
+
+- API key mode can run Codex from a background service without an interactive Codex login.
+- API keys are never shown in `/status`, `/doctor`, logs, card payloads, or exported config unless `--include-secrets --yes` is explicitly used.
+- API key injection is scoped to the Codex SDK child execution and is not added to the connector process-wide environment.
+- Changing auth mode invalidates incompatible session fingerprints.
+
+### 6.7 Codex API Key Remote Operation
+
+Codex API key mode supports Feishu remote operation because the Feishu/Lark user does not need to be physically present at the host to complete an auth prompt.
+
+Required behavior:
+
+- The bridge owner configures the key locally through `profile create`, `profile set codex.api-key`, or an equivalent secret command.
+- The bridge stores only a secret reference in normal config.
+- The SDK runner passes the key through the SDK option or a run-scoped child environment.
+- The prompt must tell Codex not to reveal or inspect bridge secret files.
+- If API key resolution fails, the run rejects before Codex starts and the user receives a non-sensitive diagnostic.
+
+Security constraints:
+
+- Default sandbox remains `workspace-write` at most.
+- `danger-full-access` is controlled by the same profile permission policy for every Codex auth mode.
+- Shell/tool output is scanned for accidental key echoes before rendering when feasible.
+
+### 6.8 Feishu/Lark CLI Identity Projection
+
+Profile field:
+
+```json
+{
+  "feishuCli": {
+    "enabled": true,
+    "identityPreset": "bot-only",
+    "configDir": "~/.feishu-codex/profiles/default/feishu-cli"
+  }
+}
+```
+
+Supported identity presets:
+
+| Preset | V1 status | Required behavior |
+|---|---|---|
+| `bot-only` | Required default | Prepare CLI config/env for the Feishu/Lark app bot identity. |
+| `user-default` | Required for personal mode | Use the local user's CLI OAuth identity only when explicitly configured. |
+| `disabled` | Required | Do not expose Feishu/Lark CLI credentials or config to Codex. |
+
+Required behavior:
+
+- Inject CLI config directory and identity env only into Codex runs.
+- Keep profile CLI config separate from host-global CLI config.
+- Show identity preset and health in `/status` and `/doctor`.
+- Deny `user-default` in group chats unless the owner explicitly allows it.
+- Add identity preset and config digest into the policy fingerprint.
+
+Acceptance criteria:
+
+- In `bot-only` mode, Codex can call configured Feishu/Lark CLI operations as the bot/app.
+- In `user-default` mode, Codex can use the local user's CLI identity for personal chats after explicit setup.
+- In `disabled` mode, Codex receives no Feishu/Lark CLI credential environment.
+- Token values never appear in rendered replies, logs, or diagnostics.
+
+## 7. Queueing and Concurrency
+
+### 7.1 Debounce
+
+Required behavior:
+
+- Default quiet window: 600 ms.
+- Multiple messages in the same scope are batched into one prompt.
+- Sender annotations are included when a batch has multiple messages.
+
+### 7.2 Active Run Rule
+
+Required behavior:
+
+- At most one active Codex run per scope.
+- Messages received during an active run are queued for the next run.
+- Commands bypass pending queue.
+
+### 7.3 Global Pool
+
+Required behavior:
+
+- Configurable max concurrent runs.
+- Excess runs wait FIFO.
+- `/doctor` may use non-waiting acquire and report pool full.
+
+## 8. Rendering
+
+### 8.1 Reply Modes
+
+Supported modes:
+
+- `card`
+- `markdown`
+- `text`
+
+Default:
+
+```text
+card for V1, markdown/text only as fallback
+```
+
+### 8.2 Run Card
+
+Card must show:
+
+- status header
+- text output
+- tool calls if enabled
+- terminal status
+- stop button while running
+- optional usage footer
+- run ID or short run reference
+- selected workspace suffix
+- sandbox/access mode
+- Codex auth mode label without secret details
+
+### 8.3 Stream Fallback
+
+Required behavior:
+
+- If streaming card creation fails, send one final markdown reply.
+- If final markdown fails due to platform audit, send a neutral safe fallback.
+
+## 9. Attachment Handling
+
+### 9.1 Supported Inputs
+
+| Resource | V1 behavior |
+|---|---|
+| Image | Download, cache, pass to Codex if policy accepts. |
+| File | Download and include path/context if policy accepts; not necessarily passed natively. |
+| Audio | Skip unless later transcribed. |
+| Video | Skip unless later supported. |
+| Sticker | Skip. |
+
+### 9.2 Policy
+
+Default limits:
+
+- max attachment count: 10
+- max per file: 25 MB
+- max per image: 25 MB
+- max total per run: 100 MB
+- cache TTL: 24 hours
+
+Rejected required attachments reject the run. Optional rejected attachments are shown in prompt context as rejected.
+
+## 10. Access Control
+
+### 10.1 Defaults
+
+- Owner can always use and administer the bot.
+- Admin list is empty by default.
+- Allowed users list is empty by default.
+- Allowed groups list is empty by default.
+- Unknown users are denied.
+- Group messages require bot mention by default.
+
+### 10.2 Owner Resolution
+
+Required behavior:
+
+- Refresh owner identity from platform APIs when possible.
+- Cache owner ID in runtime controls.
+- If refresh fails, do not widen access.
+
+### 10.3 Denial Behavior
+
+Required behavior:
+
+- Private unauthorized messages are silently ignored.
+- Group unauthorized messages are usually ignored.
+- If a disallowed group mentions the bot, a short admin instruction may be sent if policy allows.
+
+## 11. Workspace Safety
+
+Reject:
+
+- empty cwd
+- inaccessible path
+- non-directory path
+- filesystem root
+- home root
+- user root
+- broad user folders such as Desktop or Downloads
+- system roots
+- temp root
+- volume root
+
+Acceptance criteria:
+
+- Missing cwd rejects the run instead of falling back to home.
+- Workspace changes clear current thread state.
+- Workspace aliases cannot bypass realpath validation.
+
+## 12. Secrets and Local State
+
+### 12.1 State Directory
+
+Default:
+
+```text
+~/.feishu-codex
+```
+
+Profile files:
+
+```text
+profiles/<profile>/config.json
+profiles/<profile>/sessions.json
+profiles/<profile>/session-catalog.json
+profiles/<profile>/workspaces.json
+profiles/<profile>/media/
+profiles/<profile>/logs/
+profiles/<profile>/secrets.enc
+profiles/<profile>/codex-home/
+profiles/<profile>/feishu-cli/
+```
+
+### 12.2 Secret Providers
+
+Supported:
+
+- encrypted local keystore
+- environment variable
+- file
+- exec provider
+
+Secrets must never be logged or shown in `/status`.
+
+## 13. Diagnostics and Observability
+
+### 13.1 Logs
+
+Structured logs must include:
+
+- profile
+- scope
+- run ID
+- source
+- event phase
+- result
+- timing
+- sanitized error
+
+### 13.2 Doctor Report
+
+Report:
+
+- self-check
+- profile
+- backend
+- workspace
+- sandbox
+- access
+- owner status
+- queue snapshot
+- Codex availability
+- echo result
+
+### 13.3 Optional Telemetry
+
+Telemetry is disabled by default. If enabled, it must be adapter-based and must not block bridge operation.
+
+## 14. Approval Mapping
+
+V1 does not implement Codex runtime approval mapping. It uses explicit sandbox policy and non-interactive Codex execution. The app-server architecture and data model are reserved for V2:
+
+```ts
+interface ApprovalRequest {
+  id: string;
+  runId: string;
+  scopeId: string;
+  cwd: string;
+  sandbox: string;
+  action: string;
+  command?: string;
+  riskSummary?: string;
+}
+```
+
+V2 acceptance criteria:
+
+- App-server runner receives approval request.
+- Bridge sends signed approval card.
+- Only authorized actor/admin can approve.
+- Approval and denial are sent back to Codex.
+- Decision is logged with sanitized action metadata.
+
+## 15. Non-functional Requirements
+
+### 15.1 Reliability
+
+- Reconnect channel after network interruption.
+- Flush local stores on shutdown.
+- Protect local state with atomic writes.
+- Prevent duplicate runtime per profile/app.
+
+### 15.2 Security
+
+- Default no full access.
+- Default no command network access.
+- No plaintext app secret in config.
+- No plaintext Codex API key in config.
+- API key and Feishu/Lark CLI credential material are injected only into run-scoped Codex execution.
+- Signed card callbacks.
+- Policy-bound session resume.
+- Workspace validation.
+- Least-privilege group access.
+- `user-default` Feishu/Lark CLI identity is disabled for group chats unless explicitly allowed.
+
+### 15.3 Portability
+
+- macOS, Linux, Windows support.
+- Node.js 20+ target.
+- Paths normalized by platform.
+
+### 15.4 Maintainability
+
+- Runner interface isolates Codex backend changes.
+- Feishu/Lark gateway isolates platform SDK changes.
+- Policy module owns access and sandbox decisions.
+- Renderer module owns card schema.
+
+## 16. V1 Acceptance Checklist
+
+- Private owner can run a Codex task.
+- Allowed group can run a Codex task only when mention policy is satisfied.
+- Unauthorized user cannot trigger a run.
+- `/cd` switches workspace and resets session.
+- Invalid workspace rejects before Codex starts.
+- `/stop` interrupts an active run.
+- Messages during active run queue into next run.
+- Thread resumes only when cwd and policy match.
+- Images are downloaded and passed to Codex when accepted.
+- Run output streams back through a rich Feishu/Lark card.
+- Card stop callback is signed and replay-protected.
+- Markdown/text fallback works when card rendering fails.
+- Codex API key auth can run without interactive Codex login.
+- Codex API key is not logged, rendered, or exported by default.
+- Codex receives the configured profile-local Feishu/Lark CLI identity env.
+- `disabled` CLI identity mode exposes no Feishu/Lark CLI credential environment to Codex.
+- `/status` shows runtime state.
+- `/doctor` performs a low-sensitive echo run.
+- Foreground and daemon modes work.
+- Logs contain no secrets.