feishu-codex-connector 0.1.6

package/docs/ARCHITECTURE.md

@@ -0,0 +1,691 @@
+# Feishu Codex Connector Architecture
+
+## 1. Objective
+
+`feishu-codex-connector` lets authorized Feishu/Lark users control Codex from chat, topic groups, cards, and supported document comments. Feishu/Lark is the collaboration surface. Codex is the coding agent. The connector provides the policy, orchestration, state, rendering, and safety layer between them.
+
+The first version should provide a complete Codex-only connector:
+
+- Receive Feishu/Lark IM and document-comment events.
+- Normalize chat, topic, card, and comment contexts into stable run scopes.
+- Run Codex in a selected workspace with explicit sandbox policy.
+- Stream text, tool activity, status, and terminal states back through rich Feishu/Lark cards by default.
+- Support session continuity, workspace switching, stop/resume, attachments, access control, diagnostics, and daemonized operation.
+- Support Codex API key authentication as a first-class profile mode.
+- Expose profile-local Feishu/Lark CLI identity to Codex when configured.
+
+## 2. Design Principles
+
+1. Feishu/Lark is a control surface, not the execution environment.
+2. V1 is optimized for personal local runtime. Managed team and container runtimes are future modes.
+3. Every run has a policy decision before it starts.
+4. Every conversation scope has isolated workspace, queue, active run, and Codex thread state.
+5. The bridge owns all Feishu/Lark card callbacks and verifies them before any action.
+6. Codex is accessed through a runner interface, so the product can start with the TypeScript SDK and reserve app-server features.
+7. Defaults must be safe for team use: no broad workspace, no global full access, no unauthenticated card callbacks.
+8. Profile secrets, including Codex API keys, are injected only into the intended child runtime and are never logged.
+
+## 3. Recommended Technology Stack
+
+| Layer | Choice | Reason |
+|---|---|---|
+| Runtime | Node.js 20+ / TypeScript | Fits Feishu/Lark SDK, Codex TypeScript SDK, async streams, and JSON card rendering. |
+| Feishu/Lark ingress | Feishu/Lark Channel SDK over long connection | Avoids public callback URL for local runners and simplifies event normalization. |
+| Codex primary backend | `@openai/codex-sdk` | Best default for server-side programmatic Codex control. |
+| Codex auth | API key plus isolated Codex home/user-login modes | V1 must support API key login while still allowing local personal Codex auth. |
+| Codex advanced backend | `codex app-server` over stdio or Unix socket | Architecture-reserved for approval lifecycle, richer thread control, fork/archive, and turn steering. |
+| Feishu/Lark CLI identity | Profile-local CLI config directory | Lets Codex operate Feishu/Lark resources with the intended bot or user identity. |
+| Local state | JSON files with atomic writes for V1 | Simple, inspectable, easy to migrate. |
+| Secret storage | Local encrypted keystore plus env/file/exec references | Keeps app secrets out of ordinary config files. |
+| Service management | launchd, systemd user service, Windows Task Scheduler | Reliable local daemon behavior across major platforms. |
+
+## 4. System Overview
+
+```mermaid
+flowchart LR
+  F["Feishu/Lark\nIM, Topic, Card, Comment"] --> I["Channel Gateway"]
+  I --> N["Normalizer\nBridgeMessage / BridgeAction"]
+  N --> A["Access & Policy Engine"]
+  A --> CMD["Command Router"]
+  A --> Q["Run Orchestrator\nQueue, Scope, Active Run"]
+  CMD --> C["Card & Message Renderer"]
+  Q --> P["Prompt Builder"]
+  P --> R["CodexRunner Interface"]
+  R --> SDK["Codex SDK Runner\nDefault"]
+  R --> APP["App-server Runner\nAdvanced"]
+  SDK --> W["Workspace Runtime"]
+  APP --> W
+  W --> R
+  R --> EV["Event Translator"]
+  EV --> C
+  C --> F
+  Q --> ST["Session / Workspace / Registry Stores"]
+  CMD --> ST
+```
+
+## 5. Core Components
+
+### 5.1 Channel Gateway
+
+Responsibilities:
+
+- Connect to Feishu or Lark using app credentials.
+- Receive IM messages, card actions, document-comment events, reconnect signals, and SDK errors.
+- Send replies as streaming cards, streaming markdown, plain markdown, or document-comment replies.
+- Apply output throttling to avoid platform rate limits.
+- Keep raw event payloads where normalized events omit important data, such as form values or sender type.
+
+Non-goals:
+
+- It must not execute Codex.
+- It must not decide workspace or sandbox policy.
+
+### 5.2 Event Normalizer
+
+Converts platform-specific events into internal objects:
+
+```ts
+type BridgeSource = "im" | "card" | "comment";
+
+interface BridgeMessage {
+  source: BridgeSource;
+  scopeId: string;
+  chatId?: string;
+  threadId?: string;
+  commentScopeId?: string;
+  messageId: string;
+  actorId: string;
+  actorName?: string;
+  actorType?: "user" | "bot";
+  text: string;
+  mentions: BridgeMention[];
+  resources: BridgeResource[];
+  raw: unknown;
+}
+```
+
+Scope rules:
+
+| Feishu/Lark context | Scope ID |
+|---|---|
+| Private chat | `chat:<chatId>` |
+| Normal group | `chat:<chatId>` |
+| Topic group | `topic:<chatId>:<threadId>` |
+| Card callback | Same as card carrier message scope |
+| Document comment execution | `comment:<fileTokenHash>:<commentIdHash>:<nonce>` |
+| Document-level Codex continuity | `doc:<fileTokenHash>` |
+
+### 5.3 Access & Policy Engine
+
+Responsibilities:
+
+- Check whether the actor can use the bot in a private chat.
+- Check whether the group is allowed and whether mention is required.
+- Check whether the actor can run admin commands.
+- Resolve and validate the requested working directory.
+- Decide runtime access mode and Codex sandbox.
+- Validate attachments and resource bindings.
+- Generate a policy fingerprint used for safe thread resume and card callback verification.
+
+Access modes:
+
+| Bridge access | Codex sandbox | Default use |
+|---|---|---|
+| `read-only` | `read-only` | Review, explain, summarize. |
+| `workspace` | `workspace-write` | Default coding work. |
+| `full` | `danger-full-access` | Owner-only or isolated runner. |
+
+Default profile policy:
+
+```json
+{
+  "permissions": {
+    "defaultAccess": "workspace",
+    "maxAccess": "workspace"
+  },
+  "networkAccess": false
+}
+```
+
+The policy fingerprint should include at least:
+
+```text
+scopeId
+cwdRealpath
+sandbox
+networkAccess
+access policy digest
+resource scope digest
+attachment policy digest
+codex auth mode
+codexHome or runtime identity
+Feishu/Lark CLI identity preset and config digest
+```
+
+### 5.4 Command Router
+
+Built-in commands must run before ordinary messages enter the Codex queue.
+
+Command classes:
+
+- Session: `/new`, `/reset`, `/resume`
+- Workspace: `/cd`, `/ws`
+- Run control: `/stop`, `/timeout`
+- Status and diagnostics: `/status`, `/doctor`, `/help`
+- Access control: `/invite`, `/remove`
+- Runtime: `/ps`, `/exit`, `/reconnect`
+- Configuration: `/config`
+
+Admin-gated commands:
+
+```text
+/cd
+/ws
+/config
+/invite
+/remove
+/doctor
+/ps
+/exit
+/reconnect
+```
+
+`/stop` without an explicit target is allowed for the current scope. Stopping another scope is admin-only.
+
+### 5.5 Run Orchestrator
+
+Responsibilities:
+
+- Maintain one active run per scope.
+- Debounce multiple messages in a short quiet window.
+- Block a scope queue while a run is active.
+- Accumulate messages received during a run and flush them into the next run.
+- Enforce global process concurrency.
+- Submit runs to a `CodexRunner`.
+- Stop runs on `/stop`, reconnect, shutdown, or idle timeout.
+- Persist session state after Codex emits a thread ID.
+
+Queue model:
+
+```mermaid
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Debouncing: message
+  Debouncing --> Running: quiet window elapsed
+  Debouncing --> Debouncing: more messages
+  Running --> QueuedDuringRun: message
+  QueuedDuringRun --> QueuedDuringRun: more messages
+  Running --> Idle: run terminal and no queued messages
+  QueuedDuringRun --> Debouncing: run terminal
+  Running --> Idle: stop/new/cd
+```
+
+### 5.6 Prompt Builder
+
+Prompt input is structured rather than free-form concatenation.
+
+```xml
+<bridge_context>
+{"source":"im","scopeId":"topic:...","chatId":"...","actorId":"...","botOpenId":"..."}
+</bridge_context>
+
+<quoted_messages>
+[...]
+</quoted_messages>
+
+<interactive_cards>
+[...]
+</interactive_cards>
+
+<attachments>
+[{"kind":"image","path":"/local/cache/x.png","hash":"..."}]
+</attachments>
+
+<user_input>
+User text
+</user_input>
+```
+
+Bridge instructions should tell Codex:
+
+- It is running inside a Feishu/Lark bridge.
+- Bridge metadata is not user-visible and should not be repeated.
+- It must respect the provided workspace and runtime policy.
+- It should not read bridge secret files.
+- It should use profile-bound Feishu/Lark CLI environment only when available.
+- It must not bypass bridge environment variables or switch to unrelated local app credentials.
+
+### 5.7 Codex Runner Interface
+
+The bridge must not depend directly on one Codex transport.
+
+```ts
+interface CodexRunner {
+  start(input: CodexRunInput): Promise<CodexRunHandle>;
+  resume(threadId: string, input: CodexRunInput): Promise<CodexRunHandle>;
+  listThreads(input: CodexThreadListInput): Promise<CodexThreadSummary[]>;
+  stop(runId: string): Promise<void>;
+  checkAvailability(): Promise<RunnerAvailability>;
+}
+
+interface CodexRunHandle {
+  runId: string;
+  threadId?: string;
+  events: AsyncIterable<CodexBridgeEvent>;
+  stop(): Promise<void>;
+}
+```
+
+#### Default: Codex SDK Runner
+
+Used for V1 normal execution.
+
+Expected capabilities:
+
+- Start a new thread.
+- Resume a thread.
+- Stream run events.
+- Pass working directory, sandbox, images, and environment.
+- Stop using `AbortSignal`, followed by process-level fallback if needed.
+
+#### Advanced: App-server Runner
+
+Reserved for V2 or later profiles that require advanced Codex lifecycle control. It is not part of the V1 execution path.
+
+Expected capabilities:
+
+- `thread/start`, `thread/resume`, `thread/list`, `thread/archive`
+- `turn/start`, `turn/interrupt`, `turn/steer`
+- approval request/decision mapping to Feishu/Lark cards
+- schema generation and version pinning
+
+Transport policy:
+
+- Prefer stdio for local child process mode.
+- Use Unix socket for local multi-client mode.
+- Do not expose app-server WebSocket over non-loopback network in V1.
+
+### 5.8 Event Translator
+
+Codex events are translated to bridge events:
+
+```ts
+type CodexBridgeEvent =
+  | { type: "thread"; threadId: string }
+  | { type: "text"; delta: string }
+  | { type: "tool_start"; id: string; name: string; input: unknown }
+  | { type: "tool_end"; id: string; output: string; isError: boolean }
+  | { type: "usage"; inputTokens?: number; outputTokens?: number }
+  | { type: "approval_request"; request: ApprovalRequest }
+  | { type: "done"; reason: "normal" | "interrupted" | "timeout" }
+  | { type: "error"; message: string };
+```
+
+`approval_request` is reserved for the app-server runner. The SDK runner may not emit it in V1.
+
+### 5.9 Card & Message Renderer
+
+Reply modes:
+
+| Mode | Use |
+|---|---|
+| `card` | V1 default. Rich run state, tool panels, stop button, footer. |
+| `markdown` | Fallback when card creation or update fails. |
+| `text` | One final message after completion. |
+| `comment` | Plain-text document comment reply. |
+
+The renderer maintains a `RunState`:
+
+- text blocks
+- tool blocks
+- current footer
+- terminal state
+- interrupt/error/timeout markers
+- optional usage summary
+
+Card callbacks must be signed.
+
+Callback token fields:
+
+```text
+runId
+scopeId
+chatId
+operatorOpenId
+action
+policyFingerprint
+expiresAt
+nonce
+keyVersion
+```
+
+### 5.10 Session Catalog
+
+Use a catalog instead of a simple chat-to-thread map.
+
+```ts
+interface SessionCatalogEntry {
+  key: string;
+  scopeId: string;
+  cwdRealpath: string;
+  policyFingerprint: string;
+  codexThreadId: string;
+  status: "active" | "archived";
+  updatedAt: number;
+  summary?: string;
+}
+```
+
+Catalog key:
+
+```text
+scopeId + cwdRealpath + policyFingerprint
+```
+
+This prevents unsafe resume after workspace, sandbox, access, or runtime changes.
+
+### 5.11 Workspace Store
+
+Tracks current and named workspaces.
+
+```ts
+interface WorkspaceStore {
+  currentByScope: Record<string, string>;
+  aliases: Record<string, string>;
+}
+```
+
+Workspace validation must reject broad directories:
+
+- filesystem root
+- home root
+- user root
+- Desktop and Downloads as root workspace
+- system roots
+- temp root
+- volume root
+
+### 5.12 Media Store
+
+Responsibilities:
+
+- Download Feishu/Lark message resources by message ID and file key.
+- Store files by content hash.
+- Normalize MIME and extension.
+- Apply max count, max file size, total run size, and image MIME policies.
+- Remove rejected files.
+- Garbage-collect old cache entries.
+
+Images are passed to Codex. Unsupported files remain in prompt context as rejected/skipped attachments.
+
+### 5.13 Document Comment Handler
+
+Responsibilities:
+
+- React only when the bot is mentioned in supported comments.
+- Fetch comment question, quote, target document, and thread metadata.
+- Build a comment-specific prompt.
+- Run Codex without streaming UI.
+- Post a plain-text reply in the same comment thread.
+- Maintain document-level Codex continuity.
+- Avoid replying to the bridge's own comments.
+
+Comment replies should avoid Markdown because document comments often show raw formatting symbols.
+
+### 5.14 Profile Runtime
+
+Each profile has isolated:
+
+- Feishu/Lark app credentials
+- Codex runtime configuration and auth mode
+- local state and logs
+- media cache
+- session catalog
+- workspace store
+- Feishu/Lark CLI config exposed to Codex when enabled
+
+Profile config sketch:
+
+```json
+{
+  "schemaVersion": 1,
+  "activeProfile": "default",
+  "profiles": {
+    "default": {
+      "tenant": "feishu",
+      "app": {
+        "id": "cli_xxx",
+        "secret": { "source": "keystore", "id": "app-cli_xxx" }
+      },
+      "codex": {
+        "backend": "sdk",
+        "auth": {
+          "mode": "api-key",
+          "apiKey": { "source": "keystore", "id": "openai-api-key-default" }
+        },
+        "codexHome": "~/.feishu-codex/profiles/default/codex-home",
+        "inheritUserCodexHome": false
+      },
+      "feishuCli": {
+        "enabled": true,
+        "identityPreset": "bot-only",
+        "configDir": "~/.feishu-codex/profiles/default/feishu-cli"
+      },
+      "permissions": {
+        "defaultAccess": "workspace",
+        "maxAccess": "workspace",
+        "networkAccess": false
+      },
+      "access": {
+        "allowedUsers": [],
+        "allowedChats": [],
+        "admins": [],
+        "requireMentionInGroup": true
+      }
+    }
+  }
+}
+```
+
+#### Codex Authentication Modes
+
+| Mode | V1 status | Behavior |
+|---|---|---|
+| `api-key` | Required | Read a profile secret and pass it to the Codex SDK as the run API key. The key must not be exported to bridge-wide process env. |
+| `codex-home` | Required | Use an isolated profile Codex home for local Codex login state and config. |
+| `inherit-user` | Optional | Reuse the operator machine's existing Codex login only when explicitly enabled. This is convenient for personal mode but weaker for reproducibility. |
+
+API key mode is the most predictable for Feishu remote operation because the local daemon can run Codex even if no interactive Codex login exists on the host. The bridge must support secret rotation by changing the secret reference without rewriting historical logs or sessions.
+
+#### Feishu/Lark CLI Identity
+
+V1 implements profile-local Feishu/Lark CLI identity projection. When enabled, the bridge prepares a CLI config directory under the profile and injects only the required environment variables into Codex runs.
+
+Identity presets:
+
+| Preset | V1 status | Behavior |
+|---|---|---|
+| `bot-only` | Required default | Codex can use Feishu/Lark CLI capabilities that operate as the configured bot/app. |
+| `user-default` | Required for personal mode | Codex can use the local user's CLI OAuth identity when explicitly configured. |
+| `disabled` | Required | No Feishu/Lark CLI identity is exposed to Codex. |
+
+Safety rules:
+
+- The bridge must never expose host-global Feishu/Lark CLI config unless a profile explicitly opts into `user-default`.
+- Group chats should default to `bot-only` unless the owner explicitly permits user identity projection.
+- `/status` and `/doctor` show identity preset and config health, but never tokens.
+- Policy fingerprint includes CLI identity preset and profile CLI config digest.
+
+### 5.15 Runtime Registry and Locks
+
+The bridge should prevent accidental duplicate listeners.
+
+Locks:
+
+- profile lock: one process per profile
+- app lock: one process per Feishu/Lark app ID
+
+Registry:
+
+- process short ID
+- PID
+- profile
+- tenant
+- app ID
+- bot name
+- started time
+- log paths
+
+### 5.16 Observability
+
+Required logs:
+
+- structured JSONL logs
+- startup/preflight
+- event intake
+- access decisions
+- command dispatch
+- run lifecycle
+- Codex event transitions
+- queue and pool state
+- card callback verification
+- Feishu/Lark API failures
+- workspace and attachment policy decisions
+
+Metrics hooks:
+
+- run duration
+- active runs
+- queue wait
+- tokens
+- failures by phase
+- reconnect count
+- callback denials
+
+Telemetry is opt-in only.
+
+## 6. Approval Mapping Architecture
+
+V1 does not implement Codex runtime approval mapping. It uses explicit sandbox policy and non-interactive execution behavior. The architecture reserves the event type and Feishu/Lark card flow for the app-server runner in V2.
+
+```mermaid
+sequenceDiagram
+  participant C as Codex App-server
+  participant B as Bridge
+  participant F as Feishu/Lark Card
+  participant U as Authorized User
+
+  C->>B: approval_request
+  B->>B: Build approval policy context
+  B->>F: Send signed Approve/Deny card
+  U->>F: Click Approve or Deny
+  F->>B: card_action
+  B->>B: Verify signature, nonce, actor, scope, policy
+  B->>C: approval_decision
+  C->>B: Continue or fail turn
+  B->>F: Update run card
+```
+
+Approval cards must show:
+
+- requested action
+- command or tool name
+- cwd
+- sandbox
+- network request if present
+- risk summary
+- requesting run and actor
+
+Only owner/admin or the original authorized actor may approve, depending on profile policy.
+
+## 7. Deployment Modes
+
+### 7.1 Personal Local Mode
+
+- Runs on the user's workstation.
+- Uses one Feishu/Lark app.
+- Owner-only by default.
+- Primary V1 runtime mode.
+- Supports Codex API key auth, isolated Codex home, or explicit user Codex auth inheritance.
+- Supports profile-local Feishu/Lark CLI identity projection.
+- Suitable for direct workspace editing.
+
+### 7.2 Team Managed Mode
+
+- Future mode after V1.
+- Runs on a controlled host.
+- Uses per-project profiles.
+- Uses isolated Codex home.
+- Uses git worktrees or containers.
+- Produces patch or PR output instead of editing shared branches directly.
+- Requires audit logs and tighter access policy.
+
+### 7.3 Container Runner Mode
+
+- Future mode after V1.
+- Each run gets an isolated workspace.
+- Secrets are short-lived.
+- Full access may be allowed inside the container only.
+- Final artifact is diff, patch, PR, or uploaded report.
+
+## 8. Failure Handling
+
+| Failure | Handling |
+|---|---|
+| Feishu/Lark reconnect loop | Log, surface `/status`, keep retrying, allow `/reconnect`. |
+| Codex binary or SDK unavailable | Preflight failure with actionable diagnostic. |
+| Workspace invalid | Reject before run and explain. |
+| Queue full or pool full | Defer or return busy message depending on source. |
+| Stream renderer failure | Fall back to final markdown/text reply. |
+| Card callback auth failure | Deny silently or log low-detail denial. |
+| Idle run | Stop Codex, mark timeout in card. |
+| Shutdown | Stop active runs, flush stores, disconnect channel. |
+
+## 9. Milestones
+
+### V1: Codex-only Bridge
+
+- Feishu/Lark long-connection channel.
+- Codex SDK runner.
+- Codex API key authentication with profile-scoped secret references.
+- Isolated profile Codex home, with explicit personal user-auth inheritance only when configured.
+- Profile-local Feishu/Lark CLI identity projection with `bot-only`, `user-default`, and `disabled` presets.
+- IM private/group/topic support.
+- Rich CardKit run cards as the default reply surface.
+- Signed card callbacks with stop button.
+- Markdown/text fallback when card delivery fails.
+- `/new`, `/cd`, `/ws`, `/resume`, `/status`, `/stop`, `/timeout`, `/help`.
+- Interactive `/config` and status cards for core runtime settings.
+- Owner/admin/user/group access control.
+- Per-scope queue, debounce, active run tracking.
+- Workspace validation.
+- Session catalog.
+- Basic media image support.
+- Document comment handling with plain-text replies.
+- Profile config and local state.
+- Foreground run and daemon start/stop/status.
+- Structured logs and `/doctor`.
+
+### V1.5: Complete Collaboration Surface
+
+- Multi-profile service management.
+- Richer CardKit layouts and card template versioning.
+- More Feishu/Lark resource helpers behind the profile CLI identity.
+- Additional attachment types and document context expansion.
+- Packaging polish and migration helpers.
+
+### V2: Advanced Codex Control
+
+- App-server runner.
+- Approval mapping to Feishu/Lark cards.
+- Thread list/fork/archive.
+- Turn steer.
+- Worktree/container runner.
+- PR creation and diff review workflows.
+
+## 10. References
+
+- Codex SDK: `https://developers.openai.com/codex/sdk`
+- Codex app-server: `https://developers.openai.com/codex/app-server`
+- Codex sandboxing and approvals: `https://developers.openai.com/codex/concepts/sandboxing`
+- Feishu/Lark Channel SDK and long-connection event delivery: Feishu/Lark Open Platform documentation