From 39c80d3e1f78a28543ac1fad0a122998d5e35932 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Tue, 21 Apr 2026 23:38:12 +0800
Subject: [PATCH 01/21] =?UTF-8?q?=E2=9C=A8=20feat:=20add=20GitHub=20and=20?=
 =?UTF-8?q?Lark=20auth=20plugins=20for=20OAuth=20app=20credentials?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Assisted-by: claude-code:claude-sonnet-4-6
---
 cmd/anna/plugins_imports.go   |   4 +
 plugins/auth/github/plugin.go | 115 ++++++++++++++++++++++++++++
 plugins/auth/lark/plugin.go   | 137 ++++++++++++++++++++++++++++++++++
 3 files changed, 256 insertions(+)
 create mode 100644 plugins/auth/github/plugin.go
 create mode 100644 plugins/auth/lark/plugin.go

diff --git a/cmd/anna/plugins_imports.go b/cmd/anna/plugins_imports.go
index bf178af9..ad66c6d0 100644
--- a/cmd/anna/plugins_imports.go
+++ b/cmd/anna/plugins_imports.go
@@ -1,6 +1,10 @@
 package main
 
 import (
+	// Plugin auth.
+	_ "github.com/vaayne/anna/plugins/auth/github"
+	_ "github.com/vaayne/anna/plugins/auth/lark"
+
 	// Plugin channels.
 	_ "github.com/vaayne/anna/plugins/channels/feishu"
 	_ "github.com/vaayne/anna/plugins/channels/qq"
diff --git a/plugins/auth/github/plugin.go b/plugins/auth/github/plugin.go
new file mode 100644
index 00000000..331cfbb4
--- /dev/null
+++ b/plugins/auth/github/plugin.go
@@ -0,0 +1,115 @@
+package github
+
+import (
+	"fmt"
+	"maps"
+
+	pkgplugins "github.com/vaayne/anna/pkg/plugins"
+)
+
+const PluginID = "auth/github"
+
+type Config struct {
+	ClientID     string `json:"client_id"`
+	ClientSecret string `json:"client_secret"`
+}
+
+func defaultConfig() map[string]any {
+	return map[string]any{
+		"client_id":     "",
+		"client_secret": "",
+	}
+}
+
+func configSchema() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"client_id": map[string]any{
+				"type":        "string",
+				"description": "GitHub OAuth app client ID.",
+			},
+			"client_secret": map[string]any{
+				"type":        "string",
+				"description": "GitHub OAuth app client secret.",
+			},
+		},
+		"required": []any{"client_id", "client_secret"},
+	}
+}
+
+func decodeConfig(raw map[string]any) (Config, error) {
+	var cfg Config
+	if v, ok := raw["client_id"]; ok {
+		s, ok := v.(string)
+		if !ok {
+			return Config{}, fmt.Errorf("client_id: must be a string")
+		}
+		cfg.ClientID = s
+	}
+	if v, ok := raw["client_secret"]; ok {
+		s, ok := v.(string)
+		if !ok {
+			return Config{}, fmt.Errorf("client_secret: must be a string")
+		}
+		cfg.ClientSecret = s
+	}
+	return cfg, nil
+}
+
+func validateConfig(raw map[string]any) error {
+	cfg, err := decodeConfig(raw)
+	if err != nil {
+		return err
+	}
+	if cfg.ClientID == "" {
+		return fmt.Errorf("client_id: required")
+	}
+	if cfg.ClientSecret == "" {
+		return fmt.Errorf("client_secret: required")
+	}
+	return nil
+}
+
+func redactConfig(raw map[string]any) map[string]any {
+	out := make(map[string]any, len(raw))
+	maps.Copy(out, raw)
+	if _, ok := out["client_secret"]; ok {
+		out["client_secret"] = "***"
+	}
+	return out
+}
+
+func isConfigured(raw map[string]any) bool {
+	cfg, err := decodeConfig(raw)
+	return err == nil && cfg.ClientID != "" && cfg.ClientSecret != ""
+}
+
+func init() {
+	pkgplugins.Register(PluginID, pkgplugins.PluginFunc(func(host pkgplugins.Host) {
+		host.SetInfo(pkgplugins.PluginInfo{
+			ID:           PluginID,
+			Kind:         "auth",
+			Name:         "github",
+			DisplayName:  "GitHub",
+			Description:  "GitHub OAuth app credentials for device-flow authentication.",
+			AdminVisible: true,
+			HasConfig:    true,
+			Capabilities: []string{
+				pkgplugins.CapabilityConfig,
+			},
+		})
+		host.AddAdmin(pkgplugins.AdminSpec{
+			PluginID:      PluginID,
+			DefaultConfig: defaultConfig,
+			Schema:        configSchema(),
+			Validate:      validateConfig,
+			Redact:        redactConfig,
+		})
+	}))
+}
+
+// Configured reports whether the plugin has all required credentials set.
+func Configured(raw map[string]any) bool {
+	return isConfigured(raw)
+}
diff --git a/plugins/auth/lark/plugin.go b/plugins/auth/lark/plugin.go
new file mode 100644
index 00000000..38c14830
--- /dev/null
+++ b/plugins/auth/lark/plugin.go
@@ -0,0 +1,137 @@
+package lark
+
+import (
+	"fmt"
+	"maps"
+
+	pkgplugins "github.com/vaayne/anna/pkg/plugins"
+)
+
+const PluginID = "auth/lark"
+
+type Config struct {
+	AppID     string `json:"app_id"`
+	AppSecret string `json:"app_secret"`
+	Brand     string `json:"brand"`
+}
+
+func defaultConfig() map[string]any {
+	return map[string]any{
+		"app_id":     "",
+		"app_secret": "",
+		"brand":      "lark",
+	}
+}
+
+func configSchema() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"app_id": map[string]any{
+				"type":        "string",
+				"description": "Lark/Feishu OAuth app ID.",
+			},
+			"app_secret": map[string]any{
+				"type":        "string",
+				"description": "Lark/Feishu OAuth app secret.",
+			},
+			"brand": map[string]any{
+				"type":        "string",
+				"enum":        []any{"lark", "feishu"},
+				"description": "Platform brand: \"lark\" (international) or \"feishu\" (China).",
+				"default":     "lark",
+			},
+		},
+		"required": []any{"app_id", "app_secret", "brand"},
+	}
+}
+
+func decodeConfig(raw map[string]any) (Config, error) {
+	var cfg Config
+	if v, ok := raw["app_id"]; ok {
+		s, ok := v.(string)
+		if !ok {
+			return Config{}, fmt.Errorf("app_id: must be a string")
+		}
+		cfg.AppID = s
+	}
+	if v, ok := raw["app_secret"]; ok {
+		s, ok := v.(string)
+		if !ok {
+			return Config{}, fmt.Errorf("app_secret: must be a string")
+		}
+		cfg.AppSecret = s
+	}
+	if v, ok := raw["brand"]; ok {
+		s, ok := v.(string)
+		if !ok {
+			return Config{}, fmt.Errorf("brand: must be a string")
+		}
+		cfg.Brand = s
+	}
+	return cfg, nil
+}
+
+func validateConfig(raw map[string]any) error {
+	cfg, err := decodeConfig(raw)
+	if err != nil {
+		return err
+	}
+	if cfg.AppID == "" {
+		return fmt.Errorf("app_id: required")
+	}
+	if cfg.AppSecret == "" {
+		return fmt.Errorf("app_secret: required")
+	}
+	switch cfg.Brand {
+	case "lark", "feishu":
+	case "":
+		return fmt.Errorf("brand: required")
+	default:
+		return fmt.Errorf("brand: must be one of \"lark\" or \"feishu\"")
+	}
+	return nil
+}
+
+func redactConfig(raw map[string]any) map[string]any {
+	out := make(map[string]any, len(raw))
+	maps.Copy(out, raw)
+	if _, ok := out["app_secret"]; ok {
+		out["app_secret"] = "***"
+	}
+	return out
+}
+
+func isConfigured(raw map[string]any) bool {
+	cfg, err := decodeConfig(raw)
+	return err == nil && cfg.AppID != "" && cfg.AppSecret != "" && cfg.Brand != ""
+}
+
+func init() {
+	pkgplugins.Register(PluginID, pkgplugins.PluginFunc(func(host pkgplugins.Host) {
+		host.SetInfo(pkgplugins.PluginInfo{
+			ID:           PluginID,
+			Kind:         "auth",
+			Name:         "lark",
+			DisplayName:  "Lark / Feishu",
+			Description:  "Lark/Feishu OAuth app credentials for device-flow authentication.",
+			AdminVisible: true,
+			HasConfig:    true,
+			Capabilities: []string{
+				pkgplugins.CapabilityConfig,
+			},
+		})
+		host.AddAdmin(pkgplugins.AdminSpec{
+			PluginID:      PluginID,
+			DefaultConfig: defaultConfig,
+			Schema:        configSchema(),
+			Validate:      validateConfig,
+			Redact:        redactConfig,
+		})
+	}))
+}
+
+// Configured reports whether the plugin has all required credentials set.
+func Configured(raw map[string]any) bool {
+	return isConfigured(raw)
+}

From 1b49ecdd789f989de0b64eaf5376e74501e3e9c2 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Tue, 21 Apr 2026 23:44:25 +0800
Subject: [PATCH 02/21] =?UTF-8?q?=E2=9C=A8=20feat:=20add=20oauthcli=20pack?=
 =?UTF-8?q?age=20with=20device-flow=20broker=20and=20token=20manager?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements internal/oauthcli/ — host-side OAuth plumbing for GitHub and
Lark/Feishu. Includes a mutex-protected in-memory FlowStore, JSON vault
serialisation helpers, GitHubBroker (full RFC 8628 device flow with
slow_down/expired handling), LarkBroker (authorisation-code flow adapted for
device-like use with app-access-token exchange), and TokenManager with
automatic Lark access-token refresh.  LarkOAuthBundle stores AppSecret at
rest (already encrypted by the vault) so TokenManager is self-contained for
refresh without requiring the credentials at call time.

Assisted-by: claude-code:claude-sonnet-4-6
---
 internal/oauthcli/gh.go            | 296 +++++++++++++++++++++++++++++
 internal/oauthcli/lark.go          | 257 +++++++++++++++++++++++++
 internal/oauthcli/store.go         |  54 ++++++
 internal/oauthcli/token_manager.go | 149 +++++++++++++++
 internal/oauthcli/types.go         |  64 +++++++
 internal/oauthcli/vault.go         |  82 ++++++++
 6 files changed, 902 insertions(+)
 create mode 100644 internal/oauthcli/gh.go
 create mode 100644 internal/oauthcli/lark.go
 create mode 100644 internal/oauthcli/store.go
 create mode 100644 internal/oauthcli/token_manager.go
 create mode 100644 internal/oauthcli/types.go
 create mode 100644 internal/oauthcli/vault.go

diff --git a/internal/oauthcli/gh.go b/internal/oauthcli/gh.go
new file mode 100644
index 00000000..1de2f84e
--- /dev/null
+++ b/internal/oauthcli/gh.go
@@ -0,0 +1,296 @@
+package oauthcli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const (
+	ghDeviceCodeURL  = "https://github.com/login/device/code"
+	ghAccessTokenURL = "https://github.com/login/oauth/access_token"
+	ghScope          = "repo,read:org"
+)
+
+// GitHubConfig holds the OAuth app credentials for device flow.
+type GitHubConfig struct {
+	ClientID     string
+	ClientSecret string
+}
+
+// ghFlowSecret holds provider-specific secrets for an in-flight GitHub flow.
+type ghFlowSecret struct {
+	deviceCode string
+	interval   int // seconds between polls, as returned by GitHub
+	bundle     *GHOAuthBundle
+}
+
+// GitHubBroker manages GitHub device-flow sessions.
+type GitHubBroker struct {
+	cfg    GitHubConfig
+	store  *FlowStore
+	mu     sync.Mutex
+	secret map[string]*ghFlowSecret // flowID → secrets
+}
+
+// NewGitHubBroker constructs a GitHubBroker.
+func NewGitHubBroker(cfg GitHubConfig, store *FlowStore) *GitHubBroker {
+	return &GitHubBroker{
+		cfg:    cfg,
+		store:  store,
+		secret: make(map[string]*ghFlowSecret),
+	}
+}
+
+// ghDeviceCodeResponse is the JSON body from POST /login/device/code.
+type ghDeviceCodeResponse struct {
+	DeviceCode      string `json:"device_code"`
+	UserCode        string `json:"user_code"`
+	VerificationURI string `json:"verification_uri"`
+	ExpiresIn       int    `json:"expires_in"`
+	Interval        int    `json:"interval"`
+}
+
+// ghAccessTokenResponse is the JSON body from POST /login/oauth/access_token.
+type ghAccessTokenResponse struct {
+	AccessToken string `json:"access_token"`
+	TokenType   string `json:"token_type"`
+	Scope       string `json:"scope"`
+	Error       string `json:"error"`
+	// Fine-grained tokens may carry expiry.
+	ExpiresIn    int    `json:"expires_in,omitempty"`
+	RefreshToken string `json:"refresh_token,omitempty"`
+}
+
+// StartDeviceFlow requests a device code from GitHub, stores pending state,
+// and returns the FlowStatus the caller should display to the user.
+func (b *GitHubBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowStatus, error) {
+	body := url.Values{}
+	body.Set("client_id", b.cfg.ClientID)
+	body.Set("scope", ghScope)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, ghDeviceCodeURL,
+		strings.NewReader(body.Encode()))
+	if err != nil {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: build device code request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: device code request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: device code: unexpected status %d", resp.StatusCode)
+	}
+
+	var dc ghDeviceCodeResponse
+	if err := json.NewDecoder(resp.Body).Decode(&dc); err != nil {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: decode device code response: %w", err)
+	}
+
+	if dc.Interval <= 0 {
+		dc.Interval = 5 // GitHub default
+	}
+
+	flowID := uuid.NewString()
+	expiresAt := time.Now().Add(time.Duration(dc.ExpiresIn) * time.Second)
+
+	status := FlowStatus{
+		Provider:        ProviderGitHub,
+		FlowID:          flowID,
+		VerificationURI: dc.VerificationURI,
+		UserCode:        dc.UserCode,
+		ExpiresAt:       expiresAt,
+		State:           FlowStatePending,
+	}
+
+	b.store.Create(status)
+
+	b.mu.Lock()
+	b.secret[flowID] = &ghFlowSecret{
+		deviceCode: dc.DeviceCode,
+		interval:   dc.Interval,
+	}
+	b.mu.Unlock()
+
+	return status, nil
+}
+
+// Poll checks whether the user has completed authorization for flowID.
+// It updates the store state and returns the current FlowStatus.
+// Callers must call Complete after Poll returns State == FlowStateAuthorized.
+func (b *GitHubBroker) Poll(ctx context.Context, flowID string) (FlowStatus, error) {
+	status, ok := b.store.Get(flowID)
+	if !ok {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: unknown flow %q", flowID)
+	}
+
+	if status.State != FlowStatePending {
+		return status, nil
+	}
+
+	if time.Now().After(status.ExpiresAt) {
+		b.store.Update(flowID, FlowStateExpired, nil)
+		b.cleanSecret(flowID)
+		status.State = FlowStateExpired
+		return status, nil
+	}
+
+	b.mu.Lock()
+	sec, ok := b.secret[flowID]
+	b.mu.Unlock()
+	if !ok {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: missing secrets for flow %q", flowID)
+	}
+
+	reqBody := url.Values{}
+	reqBody.Set("client_id", b.cfg.ClientID)
+	reqBody.Set("device_code", sec.deviceCode)
+	reqBody.Set("grant_type", "urn:ietf:params:oauth:grant-type:device_code")
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, ghAccessTokenURL,
+		strings.NewReader(reqBody.Encode()))
+	if err != nil {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: build poll request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: poll request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	var at ghAccessTokenResponse
+	if err := json.NewDecoder(resp.Body).Decode(&at); err != nil {
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: decode poll response: %w", err)
+	}
+
+	switch at.Error {
+	case "":
+		// Success — stash the token bundle, mark authorized.
+		bundle := &GHOAuthBundle{
+			Version:      1,
+			AccessToken:  at.AccessToken,
+			TokenType:    at.TokenType,
+			Scope:        at.Scope,
+			RefreshToken: at.RefreshToken,
+		}
+		if at.ExpiresIn > 0 {
+			t := time.Now().Add(time.Duration(at.ExpiresIn) * time.Second)
+			bundle.ExpiresAt = &t
+		}
+		b.mu.Lock()
+		sec.bundle = bundle
+		b.mu.Unlock()
+		b.store.Update(flowID, FlowStateAuthorized, nil)
+		status.State = FlowStateAuthorized
+		return status, nil
+
+	case "authorization_pending":
+		// Still waiting — no change.
+		return status, nil
+
+	case "slow_down":
+		// GitHub wants us to back off; bump the stored interval and keep waiting.
+		b.mu.Lock()
+		sec.interval += 5
+		b.mu.Unlock()
+		return status, nil
+
+	case "expired_token":
+		b.store.Update(flowID, FlowStateExpired, nil)
+		b.cleanSecret(flowID)
+		status.State = FlowStateExpired
+		return status, nil
+
+	case "access_denied":
+		b.store.Update(flowID, FlowStateFailed, nil)
+		b.cleanSecret(flowID)
+		status.State = FlowStateFailed
+		return status, fmt.Errorf("oauthcli/gh: access denied by user")
+
+	default:
+		b.store.Update(flowID, FlowStateFailed, nil)
+		b.cleanSecret(flowID)
+		status.State = FlowStateFailed
+		return status, fmt.Errorf("oauthcli/gh: unexpected error %q from GitHub", at.Error)
+	}
+}
+
+// Complete persists the token bundle to vault. Must be called only after Poll
+// returns State == FlowStateAuthorized.
+func (b *GitHubBroker) Complete(ctx context.Context, vs VaultStore, userID int64, flowID string) error {
+	b.mu.Lock()
+	sec, ok := b.secret[flowID]
+	b.mu.Unlock()
+	if !ok {
+		return fmt.Errorf("oauthcli/gh: no authorized token for flow %q", flowID)
+	}
+	if sec.bundle == nil {
+		return fmt.Errorf("oauthcli/gh: flow %q is not yet authorized", flowID)
+	}
+
+	if err := SaveGHBundle(ctx, vs, userID, *sec.bundle); err != nil {
+		return err
+	}
+
+	b.store.Delete(flowID)
+	b.cleanSecret(flowID)
+	return nil
+}
+
+// PollInterval returns the current recommended seconds-between-polls for a
+// flow. Returns 5 (GitHub default) if the flow is unknown.
+func (b *GitHubBroker) PollInterval(flowID string) int {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if sec, ok := b.secret[flowID]; ok {
+		return sec.interval
+	}
+	return 5
+}
+
+func (b *GitHubBroker) cleanSecret(flowID string) {
+	b.mu.Lock()
+	delete(b.secret, flowID)
+	b.mu.Unlock()
+}
+
+// postJSON is a small helper to POST a JSON body and decode the response.
+func postJSON(ctx context.Context, url string, reqBody any, headers map[string]string, out any) error {
+	data, err := json.Marshal(reqBody)
+	if err != nil {
+		return fmt.Errorf("marshal request: %w", err)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(data))
+	if err != nil {
+		return fmt.Errorf("build request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json; charset=utf-8")
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("do request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("unexpected status %d", resp.StatusCode)
+	}
+	return json.NewDecoder(resp.Body).Decode(out)
+}
diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
new file mode 100644
index 00000000..d2c25d33
--- /dev/null
+++ b/internal/oauthcli/lark.go
@@ -0,0 +1,257 @@
+package oauthcli
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const (
+	larkBaseFeishu = "https://open.feishu.cn"
+	larkBaseLark   = "https://open.larksuite.com"
+
+	larkRedirectURI = "https://anna.app/oauth/lark/callback" // placeholder; caller sets up the real redirect
+)
+
+// LarkConfig holds the OAuth app credentials for Lark/Feishu device-style flow.
+type LarkConfig struct {
+	AppID     string
+	AppSecret string
+	Brand     string // "lark" or "feishu"
+}
+
+// larkFlowSecret holds provider-specific state for an in-flight Lark flow.
+type larkFlowSecret struct {
+	bundle *LarkOAuthBundle
+}
+
+// LarkBroker manages Lark/Feishu OAuth sessions via the authorization-code
+// flow adapted for device-like use: StartDeviceFlow returns a URL the user
+// visits; Poll checks completion; Complete exchanges the code and saves the
+// bundle to vault.
+type LarkBroker struct {
+	cfg         LarkConfig
+	store       *FlowStore
+	redirectURI string
+	mu          sync.Mutex
+	secret      map[string]*larkFlowSecret
+}
+
+// NewLarkBroker constructs a LarkBroker. redirectURI is the OAuth callback URL
+// that your HTTP handler will receive and then call Complete on.
+func NewLarkBroker(cfg LarkConfig, store *FlowStore) *LarkBroker {
+	return &LarkBroker{
+		cfg:         cfg,
+		store:       store,
+		redirectURI: larkRedirectURI,
+		secret:      make(map[string]*larkFlowSecret),
+	}
+}
+
+// WithRedirectURI returns a new broker with the same configuration but the
+// given redirect URI. The new broker has its own independent mutex and secret
+// map, so it is safe to use concurrently with the original.
+func (b *LarkBroker) WithRedirectURI(uri string) *LarkBroker {
+	return &LarkBroker{
+		cfg:         b.cfg,
+		store:       b.store,
+		redirectURI: uri,
+		secret:      make(map[string]*larkFlowSecret),
+	}
+}
+
+func (b *LarkBroker) baseURL() string {
+	if b.cfg.Brand == "feishu" {
+		return larkBaseFeishu
+	}
+	return larkBaseLark
+}
+
+// StartDeviceFlow generates a state token, constructs the authorization URL,
+// and stores a pending FlowStatus. The user must navigate to VerificationURI.
+func (b *LarkBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowStatus, error) {
+	flowID := uuid.NewString()
+	expiresAt := time.Now().Add(10 * time.Minute) // Lark code flows typically timeout within minutes
+
+	authURL, err := b.buildAuthURL(flowID)
+	if err != nil {
+		return FlowStatus{}, fmt.Errorf("oauthcli/lark: build auth url: %w", err)
+	}
+
+	status := FlowStatus{
+		Provider:        ProviderLark,
+		FlowID:          flowID,
+		VerificationURI: authURL,
+		ExpiresAt:       expiresAt,
+		State:           FlowStatePending,
+	}
+
+	b.store.Create(status)
+	b.mu.Lock()
+	b.secret[flowID] = &larkFlowSecret{}
+	b.mu.Unlock()
+
+	return status, nil
+}
+
+// Poll checks whether the flow identified by flowID has been completed.
+// Completion is signaled externally via Complete after the OAuth callback is received.
+func (b *LarkBroker) Poll(ctx context.Context, flowID string) (FlowStatus, error) {
+	status, ok := b.store.Get(flowID)
+	if !ok {
+		return FlowStatus{}, fmt.Errorf("oauthcli/lark: unknown flow %q", flowID)
+	}
+
+	if status.State != FlowStatePending {
+		return status, nil
+	}
+
+	if time.Now().After(status.ExpiresAt) {
+		b.store.Update(flowID, FlowStateExpired, nil)
+		b.cleanSecret(flowID)
+		status.State = FlowStateExpired
+		return status, nil
+	}
+
+	// Check if Complete was called and stashed a bundle.
+	b.mu.Lock()
+	sec, ok := b.secret[flowID]
+	b.mu.Unlock()
+	if ok && sec.bundle != nil {
+		status.State = FlowStateAuthorized
+		return status, nil
+	}
+
+	return status, nil
+}
+
+// Complete exchanges an authorization code for tokens, saves the bundle to
+// vault, and marks the flow as authorized. The code comes from your OAuth
+// callback handler's query parameter.
+func (b *LarkBroker) Complete(ctx context.Context, vs VaultStore, userID int64, flowID string, code string) error {
+	_, ok := b.store.Get(flowID)
+	if !ok {
+		return fmt.Errorf("oauthcli/lark: unknown flow %q", flowID)
+	}
+
+	appToken, err := b.fetchAppAccessToken(ctx)
+	if err != nil {
+		return fmt.Errorf("oauthcli/lark: fetch app access token: %w", err)
+	}
+
+	bundle, err := b.exchangeCode(ctx, appToken, code)
+	if err != nil {
+		return fmt.Errorf("oauthcli/lark: exchange code: %w", err)
+	}
+	bundle.AppID = b.cfg.AppID
+	bundle.AppSecret = b.cfg.AppSecret
+	bundle.Brand = b.cfg.Brand
+	bundle.Version = 1
+
+	if err := SaveLarkBundle(ctx, vs, userID, *bundle); err != nil {
+		return err
+	}
+
+	// Update store so polling callers see the completion immediately.
+	b.store.Update(flowID, FlowStateAuthorized, nil)
+	b.mu.Lock()
+	if sec, ok := b.secret[flowID]; ok {
+		sec.bundle = bundle
+	}
+	b.mu.Unlock()
+
+	b.store.Delete(flowID)
+	b.cleanSecret(flowID)
+	return nil
+}
+
+// larkAppTokenResponse is the JSON body from the app_access_token endpoint.
+type larkAppTokenResponse struct {
+	Code           int    `json:"code"`
+	Msg            string `json:"msg"`
+	AppAccessToken string `json:"app_access_token"`
+	Expire         int    `json:"expire"`
+}
+
+// fetchAppAccessToken obtains a short-lived Lark app access token.
+func (b *LarkBroker) fetchAppAccessToken(ctx context.Context) (string, error) {
+	endpoint := b.baseURL() + "/open-apis/auth/v3/app_access_token/internal"
+	reqBody := map[string]string{
+		"app_id":     b.cfg.AppID,
+		"app_secret": b.cfg.AppSecret,
+	}
+	var resp larkAppTokenResponse
+	if err := postJSON(ctx, endpoint, reqBody, nil, &resp); err != nil {
+		return "", fmt.Errorf("app_access_token request: %w", err)
+	}
+	if resp.Code != 0 {
+		return "", fmt.Errorf("app_access_token error %d: %s", resp.Code, resp.Msg)
+	}
+	return resp.AppAccessToken, nil
+}
+
+// larkUserTokenResponse is the JSON body from the OIDC access_token endpoint.
+type larkUserTokenResponse struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		AccessToken      string `json:"access_token"`
+		RefreshToken     string `json:"refresh_token"`
+		ExpiresIn        int    `json:"expires_in"`
+		RefreshExpiresIn int    `json:"refresh_expires_in"`
+		TokenType        string `json:"token_type"`
+	} `json:"data"`
+}
+
+// exchangeCode exchanges an authorization code for a user access token.
+func (b *LarkBroker) exchangeCode(ctx context.Context, appToken string, code string) (*LarkOAuthBundle, error) {
+	endpoint := b.baseURL() + "/open-apis/authen/v1/oidc/access_token"
+	reqBody := map[string]string{
+		"grant_type": "authorization_code",
+		"code":       code,
+	}
+	headers := map[string]string{
+		"Authorization": "Bearer " + appToken,
+	}
+	var resp larkUserTokenResponse
+	if err := postJSON(ctx, endpoint, reqBody, headers, &resp); err != nil {
+		return nil, fmt.Errorf("token exchange request: %w", err)
+	}
+	if resp.Code != 0 {
+		return nil, fmt.Errorf("token exchange error %d: %s", resp.Code, resp.Msg)
+	}
+
+	now := time.Now()
+	bundle := &LarkOAuthBundle{
+		AccessToken:      resp.Data.AccessToken,
+		RefreshToken:     resp.Data.RefreshToken,
+		AccessExpiresAt:  now.Add(time.Duration(resp.Data.ExpiresIn) * time.Second),
+		RefreshExpiresAt: now.Add(time.Duration(resp.Data.RefreshExpiresIn) * time.Second),
+	}
+	return bundle, nil
+}
+
+func (b *LarkBroker) buildAuthURL(state string) (string, error) {
+	base := b.baseURL() + "/open-apis/authen/v1/authorize"
+	params := url.Values{}
+	params.Set("app_id", b.cfg.AppID)
+	params.Set("redirect_uri", b.redirectURI)
+	params.Set("state", state)
+	params.Set("scope", "contact:user.base:readonly")
+	u, err := url.Parse(base)
+	if err != nil {
+		return "", err
+	}
+	u.RawQuery = params.Encode()
+	return u.String(), nil
+}
+
+func (b *LarkBroker) cleanSecret(flowID string) {
+	b.mu.Lock()
+	delete(b.secret, flowID)
+	b.mu.Unlock()
+}
diff --git a/internal/oauthcli/store.go b/internal/oauthcli/store.go
new file mode 100644
index 00000000..640e1e06
--- /dev/null
+++ b/internal/oauthcli/store.go
@@ -0,0 +1,54 @@
+package oauthcli
+
+import "sync"
+
+// FlowStore is an in-memory store of in-flight device-flow sessions.
+// Known limitation: a process restart loses all pending flows.
+type FlowStore struct {
+	mu    sync.Mutex
+	flows map[string]FlowStatus
+}
+
+// NewFlowStore returns an empty FlowStore.
+func NewFlowStore() *FlowStore {
+	return &FlowStore{flows: make(map[string]FlowStatus)}
+}
+
+// Create stores a new FlowStatus keyed by its FlowID.
+func (s *FlowStore) Create(status FlowStatus) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.flows[status.FlowID] = status
+}
+
+// Get returns the FlowStatus for flowID, or false if not found.
+func (s *FlowStore) Get(flowID string) (FlowStatus, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	fs, ok := s.flows[flowID]
+	return fs, ok
+}
+
+// Update sets state on the named flow and then calls update (if non-nil) to
+// allow further mutation. The state is applied first so callers can inspect or
+// override it inside update.
+func (s *FlowStore) Update(flowID string, state FlowState, update func(*FlowStatus)) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	fs, ok := s.flows[flowID]
+	if !ok {
+		return
+	}
+	fs.State = state
+	if update != nil {
+		update(&fs)
+	}
+	s.flows[flowID] = fs
+}
+
+// Delete removes the flow with the given ID from the store.
+func (s *FlowStore) Delete(flowID string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.flows, flowID)
+}
diff --git a/internal/oauthcli/token_manager.go b/internal/oauthcli/token_manager.go
new file mode 100644
index 00000000..bf9a3c54
--- /dev/null
+++ b/internal/oauthcli/token_manager.go
@@ -0,0 +1,149 @@
+package oauthcli
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+// tokenExpirySafetyMargin is subtracted from expiry times to avoid using
+// tokens that are about to expire during a long-running operation.
+const tokenExpirySafetyMargin = 2 * time.Minute
+
+// TokenManager provides host-side token validation and (for Lark) automatic
+// refresh. It reads from and writes to the vault.
+type TokenManager struct {
+	vs VaultStore
+}
+
+// NewTokenManager constructs a TokenManager backed by vs.
+func NewTokenManager(vs VaultStore) *TokenManager {
+	return &TokenManager{vs: vs}
+}
+
+// GetGHToken returns a valid GitHub access token for userID.
+// GitHub tokens obtained via device flow do not expire in standard flow, so
+// this simply returns whatever is in the vault bundle.
+func (m *TokenManager) GetGHToken(ctx context.Context, userID int64) (string, error) {
+	bundle, err := LoadGHBundle(ctx, m.vs, userID)
+	if err != nil {
+		return "", fmt.Errorf("oauthcli: get gh token: %w", err)
+	}
+	if bundle == nil {
+		return "", fmt.Errorf("oauthcli: get gh token: user %d has not connected GitHub", userID)
+	}
+	if bundle.AccessToken == "" {
+		return "", fmt.Errorf("oauthcli: get gh token: empty access token in vault for user %d", userID)
+	}
+	return bundle.AccessToken, nil
+}
+
+// GetLarkRuntimeEnv returns the environment variables needed for lark-cli.
+// It loads the Lark bundle, refreshes the access token if expired (using the
+// bundle's stored AppSecret), and returns a map ready for env injection.
+//
+// If the bundle is absent or fully expired (refresh token expired), it returns
+// a descriptive error so the runner can skip Lark env injection without failing
+// the entire session.
+func (m *TokenManager) GetLarkRuntimeEnv(ctx context.Context, userID int64, appID, brand string) (map[string]string, error) {
+	bundle, err := LoadLarkBundle(ctx, m.vs, userID)
+	if err != nil {
+		return nil, fmt.Errorf("oauthcli: get lark env: %w", err)
+	}
+	if bundle == nil {
+		return nil, fmt.Errorf("oauthcli: get lark env: user %d has not connected Lark/Feishu", userID)
+	}
+
+	now := time.Now()
+
+	// Check refresh token expiry first — if this is gone there's nothing we can do.
+	if now.After(bundle.RefreshExpiresAt.Add(-tokenExpirySafetyMargin)) {
+		return nil, fmt.Errorf(
+			"oauthcli: get lark env: user %d Lark refresh token expired at %s; please re-authorize",
+			userID, bundle.RefreshExpiresAt.Format(time.RFC3339),
+		)
+	}
+
+	// Refresh the access token if it is expired or about to expire.
+	if now.After(bundle.AccessExpiresAt.Add(-tokenExpirySafetyMargin)) {
+		refreshed, err := m.refreshLarkToken(ctx, bundle)
+		if err != nil {
+			return nil, fmt.Errorf("oauthcli: get lark env: refresh: %w", err)
+		}
+		if err := SaveLarkBundle(ctx, m.vs, userID, *refreshed); err != nil {
+			return nil, fmt.Errorf("oauthcli: get lark env: save refreshed bundle: %w", err)
+		}
+		bundle = refreshed
+	}
+
+	env := map[string]string{
+		"LARK_ACCESS_TOKEN": bundle.AccessToken,
+		"LARK_APP_ID":       bundle.AppID,
+		"LARK_BRAND":        bundle.Brand,
+	}
+	return env, nil
+}
+
+// larkRefreshResponse is the JSON body from the OIDC refresh_access_token endpoint.
+type larkRefreshResponse struct {
+	Code int    `json:"code"`
+	Msg  string `json:"msg"`
+	Data struct {
+		AccessToken      string `json:"access_token"`
+		RefreshToken     string `json:"refresh_token"`
+		ExpiresIn        int    `json:"expires_in"`
+		RefreshExpiresIn int    `json:"refresh_expires_in"`
+	} `json:"data"`
+}
+
+// refreshLarkToken exchanges the bundle's refresh token for a new access
+// token, returning an updated bundle. The original bundle is not mutated.
+func (m *TokenManager) refreshLarkToken(ctx context.Context, bundle *LarkOAuthBundle) (*LarkOAuthBundle, error) {
+	base := larkBaseFeishu
+	if bundle.Brand == "lark" {
+		base = larkBaseLark
+	}
+
+	// Obtain a fresh app access token using the stored credentials.
+	appTokenEndpoint := base + "/open-apis/auth/v3/app_access_token/internal"
+	appTokenBody := map[string]string{
+		"app_id":     bundle.AppID,
+		"app_secret": bundle.AppSecret,
+	}
+	var appTokenResp larkAppTokenResponse
+	if err := postJSON(ctx, appTokenEndpoint, appTokenBody, nil, &appTokenResp); err != nil {
+		return nil, fmt.Errorf("fetch app access token: %w", err)
+	}
+	if appTokenResp.Code != 0 {
+		return nil, fmt.Errorf("app_access_token error %d: %s", appTokenResp.Code, appTokenResp.Msg)
+	}
+
+	// Refresh the user access token.
+	refreshEndpoint := base + "/open-apis/authen/v1/oidc/refresh_access_token"
+	refreshBody := map[string]string{
+		"grant_type":    "refresh_token",
+		"refresh_token": bundle.RefreshToken,
+	}
+	headers := map[string]string{
+		"Authorization": "Bearer " + appTokenResp.AppAccessToken,
+	}
+	var refreshResp larkRefreshResponse
+	if err := postJSON(ctx, refreshEndpoint, refreshBody, headers, &refreshResp); err != nil {
+		return nil, fmt.Errorf("refresh token request: %w", err)
+	}
+	if refreshResp.Code != 0 {
+		return nil, fmt.Errorf("refresh token error %d: %s", refreshResp.Code, refreshResp.Msg)
+	}
+
+	now := time.Now()
+	refreshed := *bundle // shallow copy; all fields are value types or immutable strings
+	refreshed.AccessToken = refreshResp.Data.AccessToken
+	if refreshResp.Data.RefreshToken != "" {
+		refreshed.RefreshToken = refreshResp.Data.RefreshToken
+	}
+	refreshed.AccessExpiresAt = now.Add(time.Duration(refreshResp.Data.ExpiresIn) * time.Second)
+	if refreshResp.Data.RefreshExpiresIn > 0 {
+		refreshed.RefreshExpiresAt = now.Add(time.Duration(refreshResp.Data.RefreshExpiresIn) * time.Second)
+	}
+	return &refreshed, nil
+}
diff --git a/internal/oauthcli/types.go b/internal/oauthcli/types.go
new file mode 100644
index 00000000..25b5c77f
--- /dev/null
+++ b/internal/oauthcli/types.go
@@ -0,0 +1,64 @@
+package oauthcli
+
+import "time"
+
+// Provider identifies an OAuth provider.
+type Provider string
+
+const (
+	ProviderGitHub Provider = "github"
+	ProviderLark   Provider = "lark"
+)
+
+// FlowState is the lifecycle state of a device-flow authorization.
+type FlowState string
+
+const (
+	FlowStatePending    FlowState = "pending"
+	FlowStateAuthorized FlowState = "authorized"
+	FlowStateFailed     FlowState = "failed"
+	FlowStateExpired    FlowState = "expired"
+)
+
+// FlowStatus is the public view of an in-flight device-flow session.
+type FlowStatus struct {
+	Provider        Provider
+	FlowID          string
+	VerificationURI string
+	UserCode        string
+	ExpiresAt       time.Time
+	State           FlowState
+}
+
+// GHOAuthBundle is the versioned vault payload for GitHub.
+// GitHub personal access tokens from device flow don't expire by default,
+// but we carry optional refresh fields for future fine-grained tokens.
+type GHOAuthBundle struct {
+	Version      int        `json:"version"`
+	AccessToken  string     `json:"access_token"`
+	TokenType    string     `json:"token_type"`
+	Scope        string     `json:"scope"`
+	ExpiresAt    *time.Time `json:"expires_at,omitempty"`
+	RefreshToken string     `json:"refresh_token,omitempty"`
+}
+
+// LarkOAuthBundle is the versioned vault payload for Lark/Feishu.
+// AppSecret is stored here (already encrypted at rest in vault) so the
+// TokenManager can refresh tokens without needing the app credentials
+// passed in at call time.
+type LarkOAuthBundle struct {
+	Version          int       `json:"version"`
+	AppID            string    `json:"app_id"`
+	AppSecret        string    `json:"app_secret"`
+	Brand            string    `json:"brand"` // "lark" or "feishu"
+	AccessToken      string    `json:"access_token"`
+	RefreshToken     string    `json:"refresh_token"`
+	AccessExpiresAt  time.Time `json:"access_expires_at"`
+	RefreshExpiresAt time.Time `json:"refresh_expires_at"`
+}
+
+// Vault key names for the two supported providers.
+const (
+	VaultKeyGitHub = "GH_OAUTH"
+	VaultKeyLark   = "LARK_CLI_OAUTH"
+)
diff --git a/internal/oauthcli/vault.go b/internal/oauthcli/vault.go
new file mode 100644
index 00000000..96dcf421
--- /dev/null
+++ b/internal/oauthcli/vault.go
@@ -0,0 +1,82 @@
+package oauthcli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+)
+
+// VaultStore is the narrow interface this package needs from the vault service.
+type VaultStore interface {
+	Set(ctx context.Context, userID int64, name string, plaintext string) error
+	Delete(ctx context.Context, userID int64, name string) error
+	LoadEnv(ctx context.Context, userID int64) (map[string]string, error)
+}
+
+// SaveGHBundle serializes bundle to JSON and stores it under VaultKeyGitHub.
+func SaveGHBundle(ctx context.Context, vs VaultStore, userID int64, bundle GHOAuthBundle) error {
+	data, err := json.Marshal(bundle)
+	if err != nil {
+		return fmt.Errorf("oauthcli: marshal gh bundle: %w", err)
+	}
+	if err := vs.Set(ctx, userID, VaultKeyGitHub, string(data)); err != nil {
+		return fmt.Errorf("oauthcli: save gh bundle: %w", err)
+	}
+	return nil
+}
+
+// LoadGHBundle retrieves and deserializes the GitHub token bundle for userID.
+// Returns nil, nil if no entry exists yet.
+func LoadGHBundle(ctx context.Context, vs VaultStore, userID int64) (*GHOAuthBundle, error) {
+	env, err := vs.LoadEnv(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("oauthcli: load gh bundle: %w", err)
+	}
+	raw, ok := env[VaultKeyGitHub]
+	if !ok {
+		return nil, nil
+	}
+	var bundle GHOAuthBundle
+	if err := json.Unmarshal([]byte(raw), &bundle); err != nil {
+		return nil, fmt.Errorf("oauthcli: unmarshal gh bundle: %w", err)
+	}
+	return &bundle, nil
+}
+
+// SaveLarkBundle serializes bundle to JSON and stores it under VaultKeyLark.
+func SaveLarkBundle(ctx context.Context, vs VaultStore, userID int64, bundle LarkOAuthBundle) error {
+	data, err := json.Marshal(bundle)
+	if err != nil {
+		return fmt.Errorf("oauthcli: marshal lark bundle: %w", err)
+	}
+	if err := vs.Set(ctx, userID, VaultKeyLark, string(data)); err != nil {
+		return fmt.Errorf("oauthcli: save lark bundle: %w", err)
+	}
+	return nil
+}
+
+// LoadLarkBundle retrieves and deserializes the Lark token bundle for userID.
+// Returns nil, nil if no entry exists yet.
+func LoadLarkBundle(ctx context.Context, vs VaultStore, userID int64) (*LarkOAuthBundle, error) {
+	env, err := vs.LoadEnv(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("oauthcli: load lark bundle: %w", err)
+	}
+	raw, ok := env[VaultKeyLark]
+	if !ok {
+		return nil, nil
+	}
+	var bundle LarkOAuthBundle
+	if err := json.Unmarshal([]byte(raw), &bundle); err != nil {
+		return nil, fmt.Errorf("oauthcli: unmarshal lark bundle: %w", err)
+	}
+	return &bundle, nil
+}
+
+// DeleteBundle removes the vault entry identified by key for userID.
+func DeleteBundle(ctx context.Context, vs VaultStore, userID int64, key string) error {
+	if err := vs.Delete(ctx, userID, key); err != nil {
+		return fmt.Errorf("oauthcli: delete bundle %q: %w", key, err)
+	}
+	return nil
+}

From 1110eaf7f3ea2cf3c589d18ee337ca611903cfa9 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Tue, 21 Apr 2026 23:51:16 +0800
Subject: [PATCH 03/21] =?UTF-8?q?=E2=9C=A8=20feat:=20add=20OAuth=20CLI=20p?=
 =?UTF-8?q?rofile=20API=20routes=20and=20UI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds device-flow OAuth connect/disconnect for GitHub and Lark/Feishu
on the user profile page, with in-memory broker caching and vault persistence.

Assisted-by: claude-code:claude-sonnet-4-6
---
 internal/admin/oauth.go                      | 329 +++++++++++++++++++
 internal/admin/routes.go                     |   7 +
 internal/admin/server.go                     |  11 +
 internal/admin/ui/pages/profile.templ        |  80 +++++
 internal/admin/ui/pages/profile_templ.go     |   2 +-
 internal/admin/ui/static/js/pages/profile.js |  72 ++++
 6 files changed, 500 insertions(+), 1 deletion(-)
 create mode 100644 internal/admin/oauth.go

diff --git a/internal/admin/oauth.go b/internal/admin/oauth.go
new file mode 100644
index 00000000..54e0ef5f
--- /dev/null
+++ b/internal/admin/oauth.go
@@ -0,0 +1,329 @@
+package admin
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"github.com/vaayne/anna/internal/oauthcli"
+)
+
+const (
+	pluginIDGitHub = "auth/github"
+	pluginIDLark   = "auth/lark"
+)
+
+// larkCallbackPath is the path Lark redirects back to after user authorization.
+// It must match the redirect_uri configured in the Lark app.
+const larkCallbackPath = "/api/auth/profile/oauth/lark/callback"
+
+// getGitHubBroker returns the cached GitHubBroker, lazily constructing it from
+// the current plugin config. Returns an error if the plugin is not configured.
+func (s *Server) getGitHubBroker(ctx context.Context) (*oauthcli.GitHubBroker, error) {
+	state, err := s.pluginHost.Config().Get(ctx, pluginIDGitHub)
+	if err != nil {
+		return nil, fmt.Errorf("github plugin config unavailable: %w", err)
+	}
+	clientID, _ := state.Config["client_id"].(string)
+	clientSecret, _ := state.Config["client_secret"].(string)
+	if clientID == "" || clientSecret == "" {
+		return nil, fmt.Errorf("github OAuth app is not configured (set client_id and client_secret in auth/github plugin)")
+	}
+
+	s.oauthMu.Lock()
+	defer s.oauthMu.Unlock()
+	if s.ghBroker == nil || s.ghBrokerClientID != clientID {
+		s.ghBroker = oauthcli.NewGitHubBroker(oauthcli.GitHubConfig{
+			ClientID:     clientID,
+			ClientSecret: clientSecret,
+		}, s.flowStore)
+		s.ghBrokerClientID = clientID
+	}
+	return s.ghBroker, nil
+}
+
+// getLarkBroker returns the cached LarkBroker, lazily constructing it from the
+// current plugin config. Returns an error if the plugin is not configured.
+func (s *Server) getLarkBroker(ctx context.Context) (*oauthcli.LarkBroker, error) {
+	state, err := s.pluginHost.Config().Get(ctx, pluginIDLark)
+	if err != nil {
+		return nil, fmt.Errorf("lark plugin config unavailable: %w", err)
+	}
+	appID, _ := state.Config["app_id"].(string)
+	appSecret, _ := state.Config["app_secret"].(string)
+	brand, _ := state.Config["brand"].(string)
+	if appID == "" || appSecret == "" {
+		return nil, fmt.Errorf("lark OAuth app is not configured (set app_id and app_secret in auth/lark plugin)")
+	}
+	if brand == "" {
+		brand = "lark"
+	}
+
+	s.oauthMu.Lock()
+	defer s.oauthMu.Unlock()
+	if s.larkBroker == nil || s.larkBrokerAppID != appID {
+		redirectURI := s.corsOriginV + larkCallbackPath
+		s.larkBroker = oauthcli.NewLarkBroker(oauthcli.LarkConfig{
+			AppID:     appID,
+			AppSecret: appSecret,
+			Brand:     brand,
+		}, s.flowStore).WithRedirectURI(redirectURI)
+		s.larkBrokerAppID = appID
+	}
+	return s.larkBroker, nil
+}
+
+// flowStatusJSON is the wire representation of an in-flight OAuth flow.
+type flowStatusJSON struct {
+	Provider        string `json:"provider"`
+	FlowID          string `json:"flow_id"`
+	VerificationURI string `json:"verification_uri"`
+	UserCode        string `json:"user_code,omitempty"`
+	ExpiresAt       string `json:"expires_at"`
+	State           string `json:"state"`
+}
+
+func toFlowStatusJSON(fs oauthcli.FlowStatus) flowStatusJSON {
+	return flowStatusJSON{
+		Provider:        string(fs.Provider),
+		FlowID:          fs.FlowID,
+		VerificationURI: fs.VerificationURI,
+		UserCode:        fs.UserCode,
+		ExpiresAt:       fs.ExpiresAt.UTC().Format("2006-01-02T15:04:05Z"),
+		State:           string(fs.State),
+	}
+}
+
+// startOAuthFlow handles POST /api/auth/profile/oauth/{provider}/start.
+func (s *Server) startOAuthFlow(w http.ResponseWriter, r *http.Request) {
+	if s.vaultSvc == nil {
+		writeError(w, http.StatusServiceUnavailable, "vault not configured")
+		return
+	}
+	info := UserFromContext(r.Context())
+	if info == nil {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+
+	provider := r.PathValue("provider")
+	ctx := r.Context()
+
+	switch provider {
+	case "github":
+		broker, err := s.getGitHubBroker(ctx)
+		if err != nil {
+			writeError(w, http.StatusServiceUnavailable, err.Error())
+			return
+		}
+		status, err := broker.StartDeviceFlow(ctx, info.UserID)
+		if err != nil {
+			s.log.Error("start github device flow", "user_id", info.UserID, "error", err)
+			writeError(w, http.StatusInternalServerError, "failed to start GitHub device flow")
+			return
+		}
+		writeData(w, http.StatusOK, toFlowStatusJSON(status))
+
+	case "lark":
+		broker, err := s.getLarkBroker(ctx)
+		if err != nil {
+			writeError(w, http.StatusServiceUnavailable, err.Error())
+			return
+		}
+		status, err := broker.StartDeviceFlow(ctx, info.UserID)
+		if err != nil {
+			s.log.Error("start lark device flow", "user_id", info.UserID, "error", err)
+			writeError(w, http.StatusInternalServerError, "failed to start Lark device flow")
+			return
+		}
+		writeData(w, http.StatusOK, toFlowStatusJSON(status))
+
+	default:
+		writeError(w, http.StatusBadRequest, "unsupported provider: "+provider)
+	}
+}
+
+// pollOAuthFlow handles GET /api/auth/profile/oauth/{provider}/status/{flowID}.
+// For GitHub, if the flow is authorized this handler also calls Complete to
+// persist the token bundle to vault.
+func (s *Server) pollOAuthFlow(w http.ResponseWriter, r *http.Request) {
+	if s.vaultSvc == nil {
+		writeError(w, http.StatusServiceUnavailable, "vault not configured")
+		return
+	}
+	info := UserFromContext(r.Context())
+	if info == nil {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+
+	provider := r.PathValue("provider")
+	flowID := r.PathValue("flowID")
+	ctx := r.Context()
+
+	switch provider {
+	case "github":
+		broker, err := s.getGitHubBroker(ctx)
+		if err != nil {
+			writeError(w, http.StatusServiceUnavailable, err.Error())
+			return
+		}
+		status, err := broker.Poll(ctx, flowID)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		// Persist token as soon as authorized.
+		if status.State == oauthcli.FlowStateAuthorized {
+			if cerr := broker.Complete(ctx, s.vaultSvc, info.UserID, flowID); cerr != nil {
+				s.log.Error("complete github flow", "user_id", info.UserID, "flow_id", flowID, "error", cerr)
+				writeError(w, http.StatusInternalServerError, "failed to save GitHub credentials")
+				return
+			}
+		}
+		writeData(w, http.StatusOK, toFlowStatusJSON(status))
+
+	case "lark":
+		broker, err := s.getLarkBroker(ctx)
+		if err != nil {
+			writeError(w, http.StatusServiceUnavailable, err.Error())
+			return
+		}
+		status, err := broker.Poll(ctx, flowID)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, err.Error())
+			return
+		}
+		writeData(w, http.StatusOK, toFlowStatusJSON(status))
+
+	default:
+		writeError(w, http.StatusBadRequest, "unsupported provider: "+provider)
+	}
+}
+
+// getOAuthConnected handles GET /api/auth/profile/oauth/{provider}/connected.
+func (s *Server) getOAuthConnected(w http.ResponseWriter, r *http.Request) {
+	if s.vaultSvc == nil {
+		writeError(w, http.StatusServiceUnavailable, "vault not configured")
+		return
+	}
+	info := UserFromContext(r.Context())
+	if info == nil {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+
+	provider := r.PathValue("provider")
+	ctx := r.Context()
+
+	type connectedResp struct {
+		Connected bool   `json:"connected"`
+		Username  string `json:"username,omitempty"`
+	}
+
+	switch provider {
+	case "github":
+		bundle, err := oauthcli.LoadGHBundle(ctx, s.vaultSvc, info.UserID)
+		if err != nil {
+			s.log.Error("load gh bundle", "user_id", info.UserID, "error", err)
+			writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		if bundle == nil {
+			writeData(w, http.StatusOK, connectedResp{Connected: false})
+			return
+		}
+		writeData(w, http.StatusOK, connectedResp{Connected: true})
+
+	case "lark":
+		bundle, err := oauthcli.LoadLarkBundle(ctx, s.vaultSvc, info.UserID)
+		if err != nil {
+			s.log.Error("load lark bundle", "user_id", info.UserID, "error", err)
+			writeError(w, http.StatusInternalServerError, "internal error")
+			return
+		}
+		if bundle == nil {
+			writeData(w, http.StatusOK, connectedResp{Connected: false})
+			return
+		}
+		label := bundle.AppID
+		if bundle.Brand != "" {
+			label = bundle.Brand + ":" + bundle.AppID
+		}
+		writeData(w, http.StatusOK, connectedResp{Connected: true, Username: label})
+
+	default:
+		writeError(w, http.StatusBadRequest, "unsupported provider: "+provider)
+	}
+}
+
+// disconnectOAuth handles DELETE /api/auth/profile/oauth/{provider}.
+func (s *Server) disconnectOAuth(w http.ResponseWriter, r *http.Request) {
+	if s.vaultSvc == nil {
+		writeError(w, http.StatusServiceUnavailable, "vault not configured")
+		return
+	}
+	info := UserFromContext(r.Context())
+	if info == nil {
+		writeError(w, http.StatusUnauthorized, "not authenticated")
+		return
+	}
+
+	provider := r.PathValue("provider")
+	ctx := r.Context()
+
+	var key string
+	switch provider {
+	case "github":
+		key = oauthcli.VaultKeyGitHub
+	case "lark":
+		key = oauthcli.VaultKeyLark
+	default:
+		writeError(w, http.StatusBadRequest, "unsupported provider: "+provider)
+		return
+	}
+
+	if err := oauthcli.DeleteBundle(ctx, s.vaultSvc, info.UserID, key); err != nil {
+		s.log.Error("disconnect oauth", "provider", provider, "user_id", info.UserID, "error", err)
+		writeError(w, http.StatusInternalServerError, "failed to disconnect")
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// larkOAuthCallback handles GET /api/auth/profile/oauth/lark/callback.
+// Lark redirects the browser here after the user authorizes the app.
+// Query params: code=<auth_code>&state=<flow_id>
+func (s *Server) larkOAuthCallback(w http.ResponseWriter, r *http.Request) {
+	if s.vaultSvc == nil {
+		http.Error(w, "vault not configured", http.StatusServiceUnavailable)
+		return
+	}
+	info := UserFromContext(r.Context())
+	if info == nil {
+		http.Redirect(w, r, "/login", http.StatusFound)
+		return
+	}
+
+	code := r.URL.Query().Get("code")
+	flowID := r.URL.Query().Get("state")
+	if code == "" || flowID == "" {
+		http.Error(w, "missing code or state", http.StatusBadRequest)
+		return
+	}
+
+	ctx := r.Context()
+	broker, err := s.getLarkBroker(ctx)
+	if err != nil {
+		http.Error(w, "lark not configured", http.StatusServiceUnavailable)
+		return
+	}
+
+	if err := broker.Complete(ctx, s.vaultSvc, info.UserID, flowID, code); err != nil {
+		s.log.Error("lark oauth complete", "user_id", info.UserID, "flow_id", flowID, "error", err)
+		http.Error(w, "failed to complete Lark authorization: "+err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	http.Redirect(w, r, "/profile", http.StatusFound)
+}
diff --git a/internal/admin/routes.go b/internal/admin/routes.go
index 0d29fee0..179c5e05 100644
--- a/internal/admin/routes.go
+++ b/internal/admin/routes.go
@@ -49,6 +49,13 @@ func (s *Server) registerProfileRoutes() {
 	s.mux.HandleFunc("PUT /api/auth/profile/vault/{name}", s.setVaultEntry)
 	s.mux.HandleFunc("DELETE /api/auth/profile/vault/{name}", s.deleteVaultEntry)
 
+	// OAuth CLI device-flow (connect/disconnect GitHub and Lark credentials).
+	s.mux.HandleFunc("POST /api/auth/profile/oauth/{provider}/start", s.startOAuthFlow)
+	s.mux.HandleFunc("GET /api/auth/profile/oauth/{provider}/status/{flowID}", s.pollOAuthFlow)
+	s.mux.HandleFunc("GET /api/auth/profile/oauth/{provider}/connected", s.getOAuthConnected)
+	s.mux.HandleFunc("DELETE /api/auth/profile/oauth/{provider}", s.disconnectOAuth)
+	s.mux.HandleFunc("GET /api/auth/profile/oauth/lark/callback", s.larkOAuthCallback)
+
 	// Self-service user skills.
 	s.mux.HandleFunc("GET /api/auth/profile/skills", s.listProfileSkills)
 	s.mux.HandleFunc("POST /api/auth/profile/skills/install", s.installProfileSkill)
diff --git a/internal/admin/server.go b/internal/admin/server.go
index d971bbe3..fe4e39f8 100644
--- a/internal/admin/server.go
+++ b/internal/admin/server.go
@@ -5,12 +5,14 @@ import (
 	"database/sql"
 	"log/slog"
 	"net/http"
+	"sync"
 
 	"filippo.io/age"
 
 	"github.com/vaayne/anna/internal/agent"
 	"github.com/vaayne/anna/internal/auth"
 	"github.com/vaayne/anna/internal/config"
+	"github.com/vaayne/anna/internal/oauthcli"
 	"github.com/vaayne/anna/internal/pluginhost"
 	"github.com/vaayne/anna/internal/vault"
 	"github.com/vaayne/anna/pkg/db/sqlc"
@@ -34,6 +36,14 @@ type Server struct {
 	corsOriginV    string               // cached CORS origin
 	vaultRecipient *age.X25519Recipient // optional; if set, age keys are generated for new users
 	vaultSvc       *vault.Service       // optional; if nil, vault endpoints return 503
+
+	// OAuth CLI device-flow state.
+	flowStore        *oauthcli.FlowStore
+	oauthMu          sync.Mutex
+	ghBroker         *oauthcli.GitHubBroker // lazily initialised; guarded by oauthMu
+	ghBrokerClientID string                 // tracks which client_id ghBroker was built with
+	larkBroker       *oauthcli.LarkBroker   // lazily initialised; guarded by oauthMu
+	larkBrokerAppID  string                 // tracks which app_id larkBroker was built with
 }
 
 // New creates an admin server with all API routes mounted.
@@ -64,6 +74,7 @@ func New(store config.Store, authStore auth.AuthStore, engine *auth.PolicyEngine
 		mux:         http.NewServeMux(),
 		log:         slog.With("component", "admin"),
 		corsOriginV: corsOrigin,
+		flowStore:   oauthcli.NewFlowStore(),
 	}
 
 	s.registerRoutes()
diff --git a/internal/admin/ui/pages/profile.templ b/internal/admin/ui/pages/profile.templ
index 3ff74208..5c2daaf0 100644
--- a/internal/admin/ui/pages/profile.templ
+++ b/internal/admin/ui/pages/profile.templ
@@ -18,6 +18,86 @@ templ ProfilePage() {
 				</div>
 			</div>
 		</div>
+		<!-- OAuth CLI -->
+		<div class="mb-10">
+			<h2 class="font-serif text-xl mb-4">OAuth CLI Credentials</h2>
+			<div class="card bg-base-200">
+				<div class="card-body">
+					<p class="text-sm text-secondary">Connect your GitHub or Lark/Feishu account so anna can act on your behalf in CLI tools and runners.</p>
+					<div class="mt-4 flex flex-col gap-4">
+						<!-- GitHub -->
+						<div class="flex items-center justify-between gap-4 border border-base-300 rounded-lg p-4">
+							<div class="flex items-center gap-3">
+								<span class="font-medium text-sm">GitHub</span>
+								<template x-if="oauthStatus.github === 'connected'">
+									<span class="badge badge-success badge-sm">Connected</span>
+								</template>
+								<template x-if="oauthStatus.github === 'disconnected'">
+									<span class="badge badge-ghost badge-sm">Not connected</span>
+								</template>
+								<template x-if="oauthStatus.github === 'checking'">
+									<span class="loading loading-spinner loading-xs"></span>
+								</template>
+							</div>
+							<div>
+								<template x-if="oauthStatus.github !== 'connected'">
+									<button @click="connectOAuth('github')" :disabled="oauthFlowActive.github" class="btn btn-primary btn-sm">
+										<span x-show="oauthFlowActive.github" class="loading loading-spinner loading-xs"></span>
+										Connect
+									</button>
+								</template>
+								<template x-if="oauthStatus.github === 'connected'">
+									<button @click="disconnectOAuth('github')" class="btn btn-error btn-sm btn-outline">Disconnect</button>
+								</template>
+							</div>
+						</div>
+						<!-- GitHub device flow prompt -->
+						<template x-if="oauthFlow.github">
+							<div class="alert alert-info text-sm flex flex-col items-start gap-1 p-4">
+								<p>Open the link below and enter the code to authorize anna:</p>
+								<a :href="oauthFlow.github.verification_uri" target="_blank" class="link font-mono text-xs break-all" x-text="oauthFlow.github.verification_uri"></a>
+								<p>Code: <span class="font-mono font-bold" x-text="oauthFlow.github.user_code"></span></p>
+								<p class="text-xs text-secondary">Waiting for authorization…</p>
+							</div>
+						</template>
+						<!-- Lark / Feishu -->
+						<div class="flex items-center justify-between gap-4 border border-base-300 rounded-lg p-4">
+							<div class="flex items-center gap-3">
+								<span class="font-medium text-sm">Lark / Feishu</span>
+								<template x-if="oauthStatus.lark === 'connected'">
+									<span class="badge badge-success badge-sm">Connected</span>
+								</template>
+								<template x-if="oauthStatus.lark === 'disconnected'">
+									<span class="badge badge-ghost badge-sm">Not connected</span>
+								</template>
+								<template x-if="oauthStatus.lark === 'checking'">
+									<span class="loading loading-spinner loading-xs"></span>
+								</template>
+							</div>
+							<div>
+								<template x-if="oauthStatus.lark !== 'connected'">
+									<button @click="connectOAuth('lark')" :disabled="oauthFlowActive.lark" class="btn btn-primary btn-sm">
+										<span x-show="oauthFlowActive.lark" class="loading loading-spinner loading-xs"></span>
+										Connect
+									</button>
+								</template>
+								<template x-if="oauthStatus.lark === 'connected'">
+									<button @click="disconnectOAuth('lark')" class="btn btn-error btn-sm btn-outline">Disconnect</button>
+								</template>
+							</div>
+						</div>
+						<!-- Lark authorization link prompt -->
+						<template x-if="oauthFlow.lark">
+							<div class="alert alert-info text-sm flex flex-col items-start gap-1 p-4">
+								<p>Click the link below to authorize anna with Lark/Feishu:</p>
+								<a :href="oauthFlow.lark.verification_uri" target="_blank" class="link font-mono text-xs break-all" x-text="oauthFlow.lark.verification_uri"></a>
+								<p class="text-xs text-secondary">Waiting for authorization…</p>
+							</div>
+						</template>
+					</div>
+				</div>
+			</div>
+		</div>
 		<!-- Vault -->
 		<div class="mb-10">
 			<h2 class="font-serif text-xl mb-4">Secret Vault</h2>
diff --git a/internal/admin/ui/pages/profile_templ.go b/internal/admin/ui/pages/profile_templ.go
index 583ae04c..c87a7431 100644
--- a/internal/admin/ui/pages/profile_templ.go
+++ b/internal/admin/ui/pages/profile_templ.go
@@ -39,7 +39,7 @@ func ProfilePage() templ.Component {
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 2, "<!-- My Skills --><div class=\"mb-10\"><h2 class=\"font-serif text-xl mb-4\">My Skills</h2><div class=\"card bg-base-200\"><div class=\"card-body\"><p class=\"text-sm text-secondary\">User-scope skills available in your conversations. Not shared with other users.</p><div class=\"mt-2 flex items-center gap-3\"><button @click=\"openMySkills()\" class=\"btn btn-primary btn-sm\">Manage skills</button> <span class=\"text-xs font-mono text-secondary\" x-text=\"mySkillsCount + ' installed'\"></span></div></div></div></div><!-- Vault --><div class=\"mb-10\"><h2 class=\"font-serif text-xl mb-4\">Secret Vault</h2><div class=\"card bg-base-200\"><div class=\"card-body\"><p class=\"text-sm text-secondary\">Encrypted secrets injected as environment variables in sandbox sessions.</p><!-- Entry list --><div class=\"mt-4\" x-show=\"vaultEntries.length > 0\"><table class=\"table table-sm w-full\"><thead><tr><th class=\"font-mono text-xs\">Name</th><th class=\"font-mono text-xs\">Created</th><th class=\"font-mono text-xs\">Updated</th><th></th></tr></thead> <tbody><template x-for=\"entry in vaultEntries\" :key=\"entry.name\"><tr><td class=\"font-mono text-sm\" x-text=\"entry.name\"></td><td class=\"text-xs text-secondary\" x-text=\"formatTime(entry.created_at)\"></td><td class=\"text-xs text-secondary\" x-text=\"formatTime(entry.updated_at)\"></td><td class=\"text-right\"><button @click=\"deleteVaultEntry(entry.name)\" class=\"btn btn-ghost btn-xs btn-error\">Delete</button></td></tr></template></tbody></table></div><div x-show=\"vaultEntries.length === 0 && !vaultLoading\" class=\"mt-4\"><p class=\"text-sm text-secondary\">No secrets stored yet.</p></div><!-- Add secret form --><div class=\"mt-4 border-t border-base-300 pt-4\"><h3 class=\"text-sm font-medium mb-3\">Add Secret</h3><div class=\"grid grid-cols-1 md:grid-cols-2 gap-4\">")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 2, "<!-- My Skills --><div class=\"mb-10\"><h2 class=\"font-serif text-xl mb-4\">My Skills</h2><div class=\"card bg-base-200\"><div class=\"card-body\"><p class=\"text-sm text-secondary\">User-scope skills available in your conversations. Not shared with other users.</p><div class=\"mt-2 flex items-center gap-3\"><button @click=\"openMySkills()\" class=\"btn btn-primary btn-sm\">Manage skills</button> <span class=\"text-xs font-mono text-secondary\" x-text=\"mySkillsCount + ' installed'\"></span></div></div></div></div><!-- OAuth CLI --><div class=\"mb-10\"><h2 class=\"font-serif text-xl mb-4\">OAuth CLI Credentials</h2><div class=\"card bg-base-200\"><div class=\"card-body\"><p class=\"text-sm text-secondary\">Connect your GitHub or Lark/Feishu account so anna can act on your behalf in CLI tools and runners.</p><div class=\"mt-4 flex flex-col gap-4\"><!-- GitHub --><div class=\"flex items-center justify-between gap-4 border border-base-300 rounded-lg p-4\"><div class=\"flex items-center gap-3\"><span class=\"font-medium text-sm\">GitHub</span><template x-if=\"oauthStatus.github === 'connected'\"><span class=\"badge badge-success badge-sm\">Connected</span></template><template x-if=\"oauthStatus.github === 'disconnected'\"><span class=\"badge badge-ghost badge-sm\">Not connected</span></template><template x-if=\"oauthStatus.github === 'checking'\"><span class=\"loading loading-spinner loading-xs\"></span></template></div><div><template x-if=\"oauthStatus.github !== 'connected'\"><button @click=\"connectOAuth('github')\" :disabled=\"oauthFlowActive.github\" class=\"btn btn-primary btn-sm\"><span x-show=\"oauthFlowActive.github\" class=\"loading loading-spinner loading-xs\"></span> Connect</button></template><template x-if=\"oauthStatus.github === 'connected'\"><button @click=\"disconnectOAuth('github')\" class=\"btn btn-error btn-sm btn-outline\">Disconnect</button></template></div></div><!-- GitHub device flow prompt --><template x-if=\"oauthFlow.github\"><div class=\"alert alert-info text-sm flex flex-col items-start gap-1 p-4\"><p>Open the link below and enter the code to authorize anna:</p><a :href=\"oauthFlow.github.verification_uri\" target=\"_blank\" class=\"link font-mono text-xs break-all\" x-text=\"oauthFlow.github.verification_uri\"></a><p>Code: <span class=\"font-mono font-bold\" x-text=\"oauthFlow.github.user_code\"></span></p><p class=\"text-xs text-secondary\">Waiting for authorization…</p></div></template><!-- Lark / Feishu --><div class=\"flex items-center justify-between gap-4 border border-base-300 rounded-lg p-4\"><div class=\"flex items-center gap-3\"><span class=\"font-medium text-sm\">Lark / Feishu</span><template x-if=\"oauthStatus.lark === 'connected'\"><span class=\"badge badge-success badge-sm\">Connected</span></template><template x-if=\"oauthStatus.lark === 'disconnected'\"><span class=\"badge badge-ghost badge-sm\">Not connected</span></template><template x-if=\"oauthStatus.lark === 'checking'\"><span class=\"loading loading-spinner loading-xs\"></span></template></div><div><template x-if=\"oauthStatus.lark !== 'connected'\"><button @click=\"connectOAuth('lark')\" :disabled=\"oauthFlowActive.lark\" class=\"btn btn-primary btn-sm\"><span x-show=\"oauthFlowActive.lark\" class=\"loading loading-spinner loading-xs\"></span> Connect</button></template><template x-if=\"oauthStatus.lark === 'connected'\"><button @click=\"disconnectOAuth('lark')\" class=\"btn btn-error btn-sm btn-outline\">Disconnect</button></template></div></div><!-- Lark authorization link prompt --><template x-if=\"oauthFlow.lark\"><div class=\"alert alert-info text-sm flex flex-col items-start gap-1 p-4\"><p>Click the link below to authorize anna with Lark/Feishu:</p><a :href=\"oauthFlow.lark.verification_uri\" target=\"_blank\" class=\"link font-mono text-xs break-all\" x-text=\"oauthFlow.lark.verification_uri\"></a><p class=\"text-xs text-secondary\">Waiting for authorization…</p></div></template></div></div></div></div><!-- Vault --><div class=\"mb-10\"><h2 class=\"font-serif text-xl mb-4\">Secret Vault</h2><div class=\"card bg-base-200\"><div class=\"card-body\"><p class=\"text-sm text-secondary\">Encrypted secrets injected as environment variables in sandbox sessions.</p><!-- Entry list --><div class=\"mt-4\" x-show=\"vaultEntries.length > 0\"><table class=\"table table-sm w-full\"><thead><tr><th class=\"font-mono text-xs\">Name</th><th class=\"font-mono text-xs\">Created</th><th class=\"font-mono text-xs\">Updated</th><th></th></tr></thead> <tbody><template x-for=\"entry in vaultEntries\" :key=\"entry.name\"><tr><td class=\"font-mono text-sm\" x-text=\"entry.name\"></td><td class=\"text-xs text-secondary\" x-text=\"formatTime(entry.created_at)\"></td><td class=\"text-xs text-secondary\" x-text=\"formatTime(entry.updated_at)\"></td><td class=\"text-right\"><button @click=\"deleteVaultEntry(entry.name)\" class=\"btn btn-ghost btn-xs btn-error\">Delete</button></td></tr></template></tbody></table></div><div x-show=\"vaultEntries.length === 0 && !vaultLoading\" class=\"mt-4\"><p class=\"text-sm text-secondary\">No secrets stored yet.</p></div><!-- Add secret form --><div class=\"mt-4 border-t border-base-300 pt-4\"><h3 class=\"text-sm font-medium mb-3\">Add Secret</h3><div class=\"grid grid-cols-1 md:grid-cols-2 gap-4\">")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
diff --git a/internal/admin/ui/static/js/pages/profile.js b/internal/admin/ui/static/js/pages/profile.js
index a231443c..ec16db9e 100644
--- a/internal/admin/ui/static/js/pages/profile.js
+++ b/internal/admin/ui/static/js/pages/profile.js
@@ -26,9 +26,18 @@ export function register(Alpine) {
     newSecretName: '',
     newSecretValue: '',
 
+    // OAuth CLI
+    oauthStatus: { github: 'checking', lark: 'checking' },
+    oauthFlow: { github: null, lark: null },
+    oauthFlowActive: { github: false, lark: false },
+
     async init() {
       await this.loadMySkillsCount()
       await this.loadVaultEntries()
+      await Promise.all([
+        this.checkOAuthConnected('github'),
+        this.checkOAuthConnected('lark'),
+      ])
     },
 
     formatTime,
@@ -107,6 +116,69 @@ export function register(Alpine) {
       if (wasOpen) this.loadMySkillsCount()
     },
 
+    // --- OAuth CLI helpers ---
+
+    async checkOAuthConnected(provider) {
+      this.oauthStatus[provider] = 'checking'
+      try {
+        const data = await api('GET', `/api/auth/profile/oauth/${provider}/connected`)
+        this.oauthStatus[provider] = data && data.connected ? 'connected' : 'disconnected'
+      } catch (_) {
+        this.oauthStatus[provider] = 'disconnected'
+      }
+    },
+
+    async connectOAuth(provider) {
+      this.oauthFlowActive[provider] = true
+      this.oauthFlow[provider] = null
+      try {
+        const flow = await api('POST', `/api/auth/profile/oauth/${provider}/start`)
+        this.oauthFlow[provider] = flow
+        // Poll until terminal state.
+        await this._pollUntilDone(provider, flow.flow_id)
+      } catch (e) {
+        this.$store.toast.show(e.message, 'error')
+      } finally {
+        this.oauthFlowActive[provider] = false
+        this.oauthFlow[provider] = null
+        await this.checkOAuthConnected(provider)
+      }
+    },
+
+    async _pollUntilDone(provider, flowID) {
+      const interval = provider === 'github' ? 5000 : 3000
+      while (true) {
+        await new Promise(r => setTimeout(r, interval))
+        let status
+        try {
+          status = await api('GET', `/api/auth/profile/oauth/${provider}/status/${flowID}`)
+        } catch (_) {
+          break
+        }
+        if (!status || status.state !== 'pending') {
+          if (status && status.state === 'authorized') {
+            this.$store.toast.show(`${provider} connected successfully`)
+          } else if (status) {
+            this.$store.toast.show(`${provider} authorization ${status.state}`, 'error')
+          }
+          break
+        }
+      }
+    },
+
+    async disconnectOAuth(provider) {
+      if (!confirm(`Disconnect ${provider} credentials?`)) return
+      try {
+        await api('DELETE', `/api/auth/profile/oauth/${provider}`)
+        this.$store.toast.show(`${provider} disconnected`)
+        await this.checkOAuthConnected(provider)
+      } catch (e) {
+        this.$store.toast.show(e.message, 'error')
+      }
+    },
+
+    // --- End OAuth CLI helpers ---
+
     async changePassword() {
       if (!this.currentPassword || !this.newPassword) {
         this.$store.toast.show('Please fill in all password fields', 'error')

From dd8cdfa6b3f01fab6d87c21fe9f07aa3034e21ba Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Tue, 21 Apr 2026 23:58:41 +0800
Subject: [PATCH 04/21] =?UTF-8?q?=E2=9C=A8=20feat:=20add=20CLI=20wrapper?=
 =?UTF-8?q?=20provisioning=20and=20runner=20OAuth=20env=20injection?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add internal/cliwrap package with EnsureWrappers to write POSIX shell
  wrappers for gh and lark-cli under UserRoot/.anna/bin/
- Extend GoRunnerConfig with TokenManager, LarkAppID, LarkBrand fields
- buildSandboxEnv strips GH_OAUTH/LARK_CLI_OAUTH bundle keys from sandbox
  env and injects GH_TOKEN and Lark runtime vars via TokenManager
- Set ANNA_GH_BIN/ANNA_LARK_BIN from binaries.ToolPath so wrappers can
  locate real binaries without PATH ambiguity
- createLocalSession provisions wrappers and prepends wrapper dir to PATH
- createDockerSession provisions wrappers and sets ANNA_WRAPPER_DIR for
  Phase 5 PATH injection
- Wire TokenManager through PoolManager (auto-constructed from VaultStore
  when SetVaultEnvLoader is called) and NewRunnerFactory

Assisted-by: claude-code:claude-sonnet-4-6
---
 cmd/anna/commands.go                     |  2 +-
 cmd/anna/commands_test.go                |  6 +-
 internal/agent/factory.go                |  4 +-
 internal/agent/pool_manager.go           | 16 +++++-
 internal/agent/runner/gorunner.go        |  4 ++
 internal/agent/runner/sandbox_backend.go | 70 +++++++++++++++++++++++-
 internal/cliwrap/wrap.go                 | 38 +++++++++++++
 7 files changed, 132 insertions(+), 8 deletions(-)
 create mode 100644 internal/cliwrap/wrap.go

diff --git a/cmd/anna/commands.go b/cmd/anna/commands.go
index 0835e852..8e3e9d48 100644
--- a/cmd/anna/commands.go
+++ b/cmd/anna/commands.go
@@ -385,7 +385,7 @@ func modelSwitcher(base *config.Snapshot, store config.Store, pool *agent.Pool,
 			snap.Providers = providers
 		}
 
-		factory, err := agent.NewRunnerFactory(&snap, builtinTools, pluginToolsBuilder, providerRegistryBuilder, promptToolsFn, promptSectionsFn, toolLifecycle, skillStore, nil, nil)
+		factory, err := agent.NewRunnerFactory(&snap, builtinTools, pluginToolsBuilder, providerRegistryBuilder, promptToolsFn, promptSectionsFn, toolLifecycle, skillStore, nil, nil, nil)
 		if err != nil {
 			return err
 		}
diff --git a/cmd/anna/commands_test.go b/cmd/anna/commands_test.go
index dd906759..86d8ce05 100644
--- a/cmd/anna/commands_test.go
+++ b/cmd/anna/commands_test.go
@@ -162,7 +162,7 @@ func TestNewRunnerFactoryGo(t *testing.T) {
 	}
 	snap.Workspace = t.TempDir()
 
-	factory, err := agent.NewRunnerFactory(snap, nil, nil, testProviderRegistryBuilder, nil, nil, nil, nil, nil, nil)
+	factory, err := agent.NewRunnerFactory(snap, nil, nil, testProviderRegistryBuilder, nil, nil, nil, nil, nil, nil, nil)
 	if err != nil {
 		t.Fatalf("NewRunnerFactory: %v", err)
 	}
@@ -182,7 +182,7 @@ func TestNewRunnerFactoryUnknown(t *testing.T) {
 		Runner: config.RunnerConfig{Type: "invalid"},
 	}
 
-	_, err := agent.NewRunnerFactory(snap, nil, nil, testProviderRegistryBuilder, nil, nil, nil, nil, nil, nil)
+	_, err := agent.NewRunnerFactory(snap, nil, nil, testProviderRegistryBuilder, nil, nil, nil, nil, nil, nil, nil)
 	if err == nil {
 		t.Fatal("expected error for unknown runner type")
 	}
@@ -290,7 +290,7 @@ func TestModelSwitcherPreservesPromptBuilders(t *testing.T) {
 	}
 	snap.Workspace = t.TempDir()
 
-	initialFactory, err := agent.NewRunnerFactory(snap, nil, nil, testProviderRegistryBuilder, nil, nil, nil, nil, nil, nil)
+	initialFactory, err := agent.NewRunnerFactory(snap, nil, nil, testProviderRegistryBuilder, nil, nil, nil, nil, nil, nil, nil)
 	if err != nil {
 		t.Fatalf("NewRunnerFactory: %v", err)
 	}
diff --git a/internal/agent/factory.go b/internal/agent/factory.go
index a7808a89..a43b6cd1 100644
--- a/internal/agent/factory.go
+++ b/internal/agent/factory.go
@@ -8,6 +8,7 @@ import (
 
 	"github.com/vaayne/anna/internal/agent/runner"
 	"github.com/vaayne/anna/internal/config"
+	"github.com/vaayne/anna/internal/oauthcli"
 	coreagent "github.com/vaayne/anna/pkg/agent"
 	"github.com/vaayne/anna/pkg/hooks"
 	"github.com/vaayne/anna/pkg/memory"
@@ -25,7 +26,7 @@ import (
 //
 // Hooks are not part of the factory — they are injected via RunnerParams.HooksFn
 // by the Pool, keeping hook lifecycle fully decoupled from model/provider config.
-func NewRunnerFactory(snap *config.Snapshot, builtinTools []tools.Tool, pluginToolsBuilder PluginToolsBuilder, providerRegistryBuilder func(api, apiKey, baseURL string) (*providers.Registry, error), promptToolsFn func(context.Context) ([]pkgplugins.PromptToolInfo, error), promptSectionsFn func(context.Context, pkgplugins.SystemPromptContext) ([]pkgplugins.SystemPromptSection, error), toolLifecycle *coreagent.ToolLifecycle, skillStore pkgplugins.SkillStore, sandboxBackendFn func(ctx context.Context) string, vaultEnvLoader runner.VaultEnvLoader) (runner.NewRunnerFunc, error) {
+func NewRunnerFactory(snap *config.Snapshot, builtinTools []tools.Tool, pluginToolsBuilder PluginToolsBuilder, providerRegistryBuilder func(api, apiKey, baseURL string) (*providers.Registry, error), promptToolsFn func(context.Context) ([]pkgplugins.PromptToolInfo, error), promptSectionsFn func(context.Context, pkgplugins.SystemPromptContext) ([]pkgplugins.SystemPromptSection, error), toolLifecycle *coreagent.ToolLifecycle, skillStore pkgplugins.SkillStore, sandboxBackendFn func(ctx context.Context) string, vaultEnvLoader runner.VaultEnvLoader, tokenManager *oauthcli.TokenManager) (runner.NewRunnerFunc, error) {
 	switch snap.Runner.Type {
 	case "go":
 		return func(ctx context.Context, params runner.RunnerParams) (runner.Runner, error) {
@@ -131,6 +132,7 @@ func NewRunnerFactory(snap *config.Snapshot, builtinTools []tools.Tool, pluginTo
 				Providers:        providerRegistryBuilder,
 				UserID:           params.UserID,
 				VaultEnvLoader:   vaultEnvLoader,
+				TokenManager:     tokenManager,
 			})
 		}, nil
 	default:
diff --git a/internal/agent/pool_manager.go b/internal/agent/pool_manager.go
index 75cba620..6905c28d 100644
--- a/internal/agent/pool_manager.go
+++ b/internal/agent/pool_manager.go
@@ -10,6 +10,7 @@ import (
 
 	"github.com/vaayne/anna/internal/agent/runner"
 	"github.com/vaayne/anna/internal/config"
+	"github.com/vaayne/anna/internal/oauthcli"
 	coreagent "github.com/vaayne/anna/pkg/agent"
 	"github.com/vaayne/anna/pkg/hooks"
 	"github.com/vaayne/anna/pkg/memory"
@@ -131,6 +132,13 @@ func WithVaultEnvLoader(v runner.VaultEnvLoader) PoolManagerOption {
 	}
 }
 
+// WithTokenManager sets the OAuth token manager for runtime token injection.
+func WithTokenManager(tm *oauthcli.TokenManager) PoolManagerOption {
+	return func(pm *PoolManager) {
+		pm.tokenManager = tm
+	}
+}
+
 // PoolManager manages a map of agent ID to Pool. It reads enabled agents
 // from the config Store and creates one Pool per agent.
 type PoolManager struct {
@@ -152,6 +160,7 @@ type PoolManager struct {
 	builtinToolsFactory     BuiltinToolsFactory
 	skillStore              pkgplugins.SkillStore
 	vaultEnvLoader          runner.VaultEnvLoader
+	tokenManager            *oauthcli.TokenManager
 	log                     *slog.Logger
 }
 
@@ -172,9 +181,14 @@ func NewPoolManager(store config.Store, mem memory.Provider, opts ...PoolManager
 
 // SetVaultEnvLoader sets the vault env loader and rebuilds all pool factories
 // so existing pools pick up the loader. Must be called after StartAll.
+// If vs also satisfies oauthcli.VaultStore, a TokenManager is constructed and
+// wired into the pool manager so runners can inject runtime OAuth tokens.
 func (pm *PoolManager) SetVaultEnvLoader(ctx context.Context, v runner.VaultEnvLoader) {
 	pm.mu.Lock()
 	pm.vaultEnvLoader = v
+	if vs, ok := v.(oauthcli.VaultStore); ok {
+		pm.tokenManager = oauthcli.NewTokenManager(vs)
+	}
 	pools := make(map[string]*Pool, len(pm.pools))
 	maps.Copy(pools, pm.pools)
 	pm.mu.Unlock()
@@ -440,7 +454,7 @@ func (pm *PoolManager) buildFactory(_ context.Context, snap *config.Snapshot) (r
 		plugins, _ := pm.store.ListPlugins(ctx)
 		return config.ActiveSandboxBackend(plugins)
 	}
-	return NewRunnerFactory(snap, builtinTools, pm.pluginToolsBuilder, pm.providerRegistryBuilder, pm.promptToolsBuilder, pm.promptSectionsBuilder, pm.toolLifecycle, pm.skillStore, sandboxBackendFn, pm.vaultEnvLoader)
+	return NewRunnerFactory(snap, builtinTools, pm.pluginToolsBuilder, pm.providerRegistryBuilder, pm.promptToolsBuilder, pm.promptSectionsBuilder, pm.toolLifecycle, pm.skillStore, sandboxBackendFn, pm.vaultEnvLoader, pm.tokenManager)
 }
 
 // mergeTools creates a new slice containing builtin tools followed by more
diff --git a/internal/agent/runner/gorunner.go b/internal/agent/runner/gorunner.go
index ec20ada2..17cba6be 100644
--- a/internal/agent/runner/gorunner.go
+++ b/internal/agent/runner/gorunner.go
@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/vaayne/anna/internal/config"
+	"github.com/vaayne/anna/internal/oauthcli"
 	builtinres "github.com/vaayne/anna/internal/resources"
 	"github.com/vaayne/anna/internal/resources/binaries"
 	coreagent "github.com/vaayne/anna/pkg/agent"
@@ -58,6 +59,9 @@ type GoRunnerConfig struct {
 	SandboxBackendFn func(ctx context.Context) string // resolves active backend at session time; overrides Sandbox.Backend
 	UserID           int64                            // auth user ID; used for vault secret injection
 	VaultEnvLoader   VaultEnvLoader                   // optional; if set, vault secrets are injected into sandbox env
+	TokenManager     *oauthcli.TokenManager           // optional; if set, runtime OAuth tokens are injected into sandbox env
+	LarkAppID        string                           // optional Lark app_id from plugin config
+	LarkBrand        string                           // optional Lark brand: "lark" or "feishu"
 }
 
 // GoRunner implements Runner by calling LLM providers directly via agent.Runner.
diff --git a/internal/agent/runner/sandbox_backend.go b/internal/agent/runner/sandbox_backend.go
index 5893d51e..fe1f965c 100644
--- a/internal/agent/runner/sandbox_backend.go
+++ b/internal/agent/runner/sandbox_backend.go
@@ -6,12 +6,16 @@ import (
 	"log/slog"
 	"maps"
 	"os"
+	"path/filepath"
 	"sync"
 
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/trace"
 
+	"github.com/vaayne/anna/internal/cliwrap"
 	"github.com/vaayne/anna/internal/config"
+	"github.com/vaayne/anna/internal/oauthcli"
+	"github.com/vaayne/anna/internal/resources/binaries"
 	"github.com/vaayne/anna/internal/sandbox"
 	dockerplugin "github.com/vaayne/anna/plugins/sandbox/docker"
 	"github.com/vaayne/anna/plugins/sandbox/docker/dockerclient"
@@ -138,6 +142,43 @@ func buildSandboxEnv(ctx context.Context, cfg GoRunnerConfig, paths sandboxPaths
 		}
 	}
 
+	// OAuth bundle keys are host-side only: they hold raw JSON credentials and
+	// must not reach the sandbox process. The runner injects derived runtime
+	// tokens below instead.
+	delete(env, oauthcli.VaultKeyGitHub)
+	delete(env, oauthcli.VaultKeyLark)
+
+	// Inject runtime OAuth tokens when a TokenManager is available.
+	if cfg.TokenManager != nil {
+		if token, err := cfg.TokenManager.GetGHToken(ctx, cfg.UserID); err == nil && token != "" {
+			env["GH_TOKEN"] = token
+		} else if err != nil {
+			slog.Debug("gh token injection skipped",
+				"component", "runner_sandbox",
+				"user_id", cfg.UserID,
+				"error", err,
+			)
+		}
+
+		if larkEnv, err := cfg.TokenManager.GetLarkRuntimeEnv(ctx, cfg.UserID, cfg.LarkAppID, cfg.LarkBrand); err == nil {
+			maps.Copy(env, larkEnv)
+		} else {
+			slog.Debug("lark env injection skipped",
+				"component", "runner_sandbox",
+				"user_id", cfg.UserID,
+				"error", err,
+			)
+		}
+	}
+
+	// Set real binary paths so wrapper scripts can locate them.
+	if ghPath := binaries.ToolPath(paths.AnnaHome, "gh"); ghPath != "" {
+		env["ANNA_GH_BIN"] = ghPath
+	}
+	if larkPath := binaries.ToolPath(paths.AnnaHome, "lark-cli"); larkPath != "" {
+		env["ANNA_LARK_BIN"] = larkPath
+	}
+
 	// Runner-set vars overlay vault entries so they always take precedence.
 	maps.Copy(env, sandboxProcessEnv(paths))
 	return env
@@ -160,12 +201,23 @@ func createDockerSession(ctx context.Context, cfg GoRunnerConfig) (*runnerSessio
 		recordSandboxError(span, err)
 		return nil, err
 	}
+	env := buildSandboxEnv(ctx, cfg, paths)
+
+	// Provision CLI wrappers under the user wrapper dir; expose the dir path via
+	// ANNA_WRAPPER_DIR so Phase 5 can add it to PATH inside the container.
+	wrapperDir := filepath.Join(paths.UserRoot, ".anna", "bin")
+	if err := cliwrap.EnsureWrappers(wrapperDir); err != nil {
+		slog.Warn("cliwrap provision failed", "component", "runner_sandbox", "error", err)
+	} else {
+		env["ANNA_WRAPPER_DIR"] = wrapperDir
+	}
+
 	policy := sandbox.Policy{
 		Filesystem: runnerFilesystemPolicy(paths),
 		Network: sandbox.NetworkPolicy{
 			Mode: sandbox.NetworkMode(cfg.Sandbox.Network.Mode),
 		},
-		Env:        buildSandboxEnv(ctx, cfg, paths),
+		Env:        env,
 		InheritEnv: true,
 	}
 
@@ -212,12 +264,26 @@ func createLocalSession(ctx context.Context, cfg GoRunnerConfig) (*runnerSession
 	if err != nil {
 		return nil, fmt.Errorf("resolve sandbox paths: %w", err)
 	}
+	env := buildSandboxEnv(ctx, cfg, paths)
+
+	// Provision CLI wrappers and prepend wrapper dir to PATH for local sessions.
+	wrapperDir := filepath.Join(paths.UserRoot, ".anna", "bin")
+	if err := cliwrap.EnsureWrappers(wrapperDir); err != nil {
+		slog.Warn("cliwrap provision failed", "component", "runner_sandbox", "error", err)
+	} else {
+		existing := env["PATH"]
+		if existing == "" {
+			existing = os.Getenv("PATH")
+		}
+		env["PATH"] = wrapperDir + string(os.PathListSeparator) + existing
+	}
+
 	policy := sandbox.Policy{
 		Filesystem: runnerFilesystemPolicy(paths),
 		Network: sandbox.NetworkPolicy{
 			Mode: sandbox.NetworkMode(cfg.Sandbox.Network.Mode),
 		},
-		Env:        buildSandboxEnv(ctx, cfg, paths),
+		Env:        env,
 		InheritEnv: true,
 	}
 
diff --git a/internal/cliwrap/wrap.go b/internal/cliwrap/wrap.go
new file mode 100644
index 00000000..def28c17
--- /dev/null
+++ b/internal/cliwrap/wrap.go
@@ -0,0 +1,38 @@
+// Package cliwrap provisions thin POSIX shell wrapper scripts for CLI tools
+// (gh, lark-cli) under a user-owned bin directory. The wrappers rely on
+// environment variables injected by the runner (ANNA_GH_BIN, ANNA_LARK_BIN)
+// to locate the real binaries, avoiding infinite exec loops.
+package cliwrap
+
+import (
+	"os"
+	"path/filepath"
+)
+
+const (
+	// ghWrapper is the shell script placed at binDir/gh.
+	// It delegates to the real binary path exported by the runner as ANNA_GH_BIN.
+	ghWrapper = "#!/bin/sh\nexec \"${ANNA_GH_BIN:-gh}\" \"$@\"\n"
+
+	// larkWrapper is the shell script placed at binDir/lark-cli.
+	// It delegates to the real binary path exported by the runner as ANNA_LARK_BIN.
+	larkWrapper = "#!/bin/sh\nexec \"${ANNA_LARK_BIN:-lark-cli}\" \"$@\"\n"
+)
+
+// EnsureWrappers creates wrapper scripts for gh and lark-cli under binDir.
+// binDir is typically UserRoot/.anna/bin/.
+// The wrappers are re-written on every call so stale content is never left behind.
+func EnsureWrappers(binDir string) error {
+	if err := os.MkdirAll(binDir, 0o755); err != nil {
+		return err
+	}
+	if err := writeExecutable(filepath.Join(binDir, "gh"), ghWrapper); err != nil {
+		return err
+	}
+	return writeExecutable(filepath.Join(binDir, "lark-cli"), larkWrapper)
+}
+
+// writeExecutable atomically writes content to path with executable permissions.
+func writeExecutable(path, content string) error {
+	return os.WriteFile(path, []byte(content), 0o755)
+}

From ae4400097a1da7c0853c027d0007daf38877f9d1 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 00:01:35 +0800
Subject: [PATCH 05/21] =?UTF-8?q?=E2=9C=A8=20feat:=20inject=20wrapper=20PA?=
 =?UTF-8?q?TH=20in=20Docker=20sessions=20and=20add=20gh/lark-cli=20to=20sa?=
 =?UTF-8?q?ndbox=20image?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add injectWrapperPath helper: translates ANNA_WRAPPER_DIR to a container PATH
  prepend so CLI wrappers provisioned in UserRoot/.anna/bin/ are found by exec
- Add injectDockerBinPaths helper: overrides ANNA_GH_BIN/ANNA_LARK_BIN to
  container-side absolute paths (/usr/bin/gh, /usr/local/bin/lark-cli) so
  wrapper scripts never loop back through themselves
- Apply both helpers in dockerHost.Exec and dockerHost.StartProcess after
  translateEnvPaths
- Dockerfile: install gh 2.89.0 via official apt repo; install lark-cli 1.0.15
  from GitHub release tarball

Assisted-by: claude-code:claude-sonnet-4-6
---
 plugins/sandbox/docker/Dockerfile | 27 ++++++++++++++++++++
 plugins/sandbox/docker/session.go | 41 +++++++++++++++++++++++++++++--
 2 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/plugins/sandbox/docker/Dockerfile b/plugins/sandbox/docker/Dockerfile
index bfabae42..f75a9e10 100644
--- a/plugins/sandbox/docker/Dockerfile
+++ b/plugins/sandbox/docker/Dockerfile
@@ -24,6 +24,33 @@ RUN apt-get update && \
     ln -s /usr/bin/fdfind /usr/local/bin/fd && \
     apt-get clean && rm -rf /var/lib/apt/lists/*
 
+# GitHub CLI (gh) — version pinned to match internal/builddeps/binaries.go ghCLIVersion
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        | tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
+    apt-get update && \
+    apt-get install -y gh=2.89.0 && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# lark-cli — version pinned to match internal/builddeps/binaries.go larkCLIVersion
+# Released as a tarball from github.com/larksuite/cli at /usr/local/bin/lark-cli
+# (injectDockerBinPaths in plugins/sandbox/docker/session.go relies on this path)
+ARG LARK_CLI_VERSION=1.0.15
+RUN set -eux; \
+    ARCH="$(dpkg --print-architecture)"; \
+    case "$ARCH" in \
+        amd64) LARK_ARCH="linux-amd64" ;; \
+        arm64) LARK_ARCH="linux-arm64" ;; \
+        *) echo "unsupported architecture: $ARCH" >&2; exit 1 ;; \
+    esac; \
+    curl -fsSL \
+        "https://github.com/larksuite/cli/releases/download/v${LARK_CLI_VERSION}/lark-cli-${LARK_CLI_VERSION}-${LARK_ARCH}.tar.gz" \
+        -o /tmp/lark-cli.tar.gz && \
+    tar -xzf /tmp/lark-cli.tar.gz -C /tmp && \
+    find /tmp -name "lark-cli" -type f -exec install -m 755 {} /usr/local/bin/lark-cli \; && \
+    rm -f /tmp/lark-cli.tar.gz
+
 ARG USER_UID=1000
 ARG USER_GID=1000
 
diff --git a/plugins/sandbox/docker/session.go b/plugins/sandbox/docker/session.go
index c5227c0e..90d2646f 100644
--- a/plugins/sandbox/docker/session.go
+++ b/plugins/sandbox/docker/session.go
@@ -227,6 +227,43 @@ func translateEnvPaths(env map[string]string, mountTable []dockerclient.Mount) m
 	return out
 }
 
+// containerDefaultPATH is the image-baked PATH from the Dockerfile ENV directive.
+// It is used as the base when building a container exec PATH that prepends the
+// wrapper dir. Keep in sync with the ENV PATH line in plugins/sandbox/docker/Dockerfile.
+const containerDefaultPATH = "/home/anna/.local/bin:/home/anna/.local/share/mise/shims:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
+// injectWrapperPath prepends the wrapper dir (ANNA_WRAPPER_DIR) to the
+// container exec PATH so that CLI wrappers provisioned in that directory
+// shadow the real binaries and intercept calls for auth injection.
+//
+// ANNA_WRAPPER_DIR is translated by translateEnvPaths from a host path to its
+// container-side equivalent before this function is called. If the variable is
+// absent or empty (translation failed because the dir is not inside a mount),
+// the env is returned unchanged.
+func injectWrapperPath(env map[string]string) map[string]string {
+	wrapperDir, ok := env["ANNA_WRAPPER_DIR"]
+	if !ok || wrapperDir == "" {
+		return env
+	}
+	base := env["PATH"]
+	if base == "" {
+		base = containerDefaultPATH
+	}
+	env["PATH"] = wrapperDir + ":" + base
+	return env
+}
+
+// injectDockerBinPaths overrides ANNA_GH_BIN and ANNA_LARK_BIN with their
+// absolute container-side paths. The runner sets these to host paths via
+// binaries.ToolPath; those paths do not exist inside the container.
+// Overriding them here ensures the wrapper scripts exec the real binaries
+// rather than looping back through the wrappers on PATH.
+func injectDockerBinPaths(env map[string]string) map[string]string {
+	env["ANNA_GH_BIN"] = "/usr/bin/gh"
+	env["ANNA_LARK_BIN"] = "/usr/local/bin/lark-cli"
+	return env
+}
+
 // dockerSession is a docker-backed sandbox session backed by a single container.
 type dockerSession struct {
 	id          string
@@ -482,7 +519,7 @@ func (h *dockerHost) Exec(ctx context.Context, command string, opts sandboxpkg.E
 		return sandboxpkg.ExecResult{}, fmt.Errorf("docker host exec: cwd not in any mount: %w", err)
 	}
 
-	env := translateEnvPaths(mergeEnv(h.session.policy.Env, opts.Env), h.session.mountTable)
+	env := injectDockerBinPaths(injectWrapperPath(translateEnvPaths(mergeEnv(h.session.policy.Env, opts.Env), h.session.mountTable)))
 
 	timeout := opts.Timeout
 	if timeout == 0 {
@@ -527,7 +564,7 @@ func (h *dockerHost) StartProcess(ctx context.Context, req sandboxpkg.ProcessReq
 		return nil, fmt.Errorf("docker host start_process: cwd not in any mount: %w", err)
 	}
 
-	env := translateEnvPaths(mergeEnv(h.session.policy.Env, req.Env), h.session.mountTable)
+	env := injectDockerBinPaths(injectWrapperPath(translateEnvPaths(mergeEnv(h.session.policy.Env, req.Env), h.session.mountTable)))
 
 	timeout := req.Timeout
 	if timeout == 0 {

From 4247d14685e3421f5aed391bb2aed262826f0a1f Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 00:08:27 +0800
Subject: [PATCH 06/21] =?UTF-8?q?=E2=9C=A8=20feat:=20add=20tests=20and=20d?=
 =?UTF-8?q?ocs=20for=20OAuth=20CLI=20feature?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Assisted-by: claude-code:claude-sonnet-4-6
---
 docs/content/docs/features/cli-oauth.md       |  68 +++++++
 docs/content/docs/features/cli-oauth.zh.md    |  50 +++++
 docs/content/docs/features/meta.json          |   2 +-
 docs/content/docs/features/meta.zh.json       |   2 +-
 internal/agent/runner/sandbox_backend_test.go |  38 ++++
 internal/cliwrap/wrap_test.go                 | 103 ++++++++++
 internal/oauthcli/store_test.go               | 108 +++++++++++
 internal/oauthcli/vault_test.go               | 182 ++++++++++++++++++
 .../resources/skills/system/anna/SKILL.md     |   1 +
 plugins/sandbox/docker/session_pure_test.go   |  77 ++++++++
 10 files changed, 629 insertions(+), 2 deletions(-)
 create mode 100644 docs/content/docs/features/cli-oauth.md
 create mode 100644 docs/content/docs/features/cli-oauth.zh.md
 create mode 100644 internal/cliwrap/wrap_test.go
 create mode 100644 internal/oauthcli/store_test.go
 create mode 100644 internal/oauthcli/vault_test.go

diff --git a/docs/content/docs/features/cli-oauth.md b/docs/content/docs/features/cli-oauth.md
new file mode 100644
index 00000000..923f211d
--- /dev/null
+++ b/docs/content/docs/features/cli-oauth.md
@@ -0,0 +1,68 @@
+---
+title: CLI OAuth
+---
+
+## Overview
+
+The CLI OAuth feature lets agents use `gh` (GitHub CLI) and `lark-cli` directly from
+sandbox sessions without manual authentication. Anna handles the OAuth device flow on
+the host, stores a versioned token bundle in your personal vault, and injects a fresh
+runtime token into each sandbox environment automatically.
+
+## Prerequisites
+
+An admin must configure the relevant auth plugin with application credentials before
+any user can connect:
+
+- **GitHub**: The admin must set a GitHub OAuth app's client ID and secret in the
+  GitHub auth plugin settings.
+- **Lark / Feishu**: The admin must set a Lark app ID, app secret, and brand
+  (`lark` or `feishu`) in the Lark auth plugin settings.
+
+## Connecting
+
+1. Open the Anna admin panel and navigate to your **Profile** page.
+2. Find the **OAuth CLI Credentials** section.
+3. Click **Connect** next to the provider you want to link.
+4. Anna starts a device flow and displays a verification URL and user code.
+5. Open the URL in a browser, enter the code, and authorize.
+6. Anna polls for completion. Once authorized, the token bundle is saved to your vault.
+
+You can disconnect at any time by clicking **Disconnect** next to the provider.
+
+## Using the CLIs
+
+After connecting, raw `gh` and `lark-cli` commands work inside agent sandbox sessions
+without any additional configuration. Anna prepends a wrapper directory to `PATH` so
+that every `gh` or `lark-cli` invocation automatically receives the correct credentials.
+
+Example (issued by the agent inside a bash tool call):
+
+```sh
+gh issue list --repo owner/repo
+lark-cli message send --chat-id <id> --text "Hello"
+```
+
+## Known limitations
+
+### Lark token expiry
+
+Lark user access tokens expire after approximately **2 hours**. Anna refreshes them
+at session start only. If an agent session outlives the token, `lark-cli` calls will
+fail with an authentication error. Starting a new Anna session will pick up a freshly
+refreshed token automatically.
+
+### Restart loses in-flight device flows
+
+Pending device flows (started but not yet authorized) are held in memory. An Anna
+process restart discards them. If Anna restarts while you are completing authorization
+in a browser, you will need to start the flow again from the profile page.
+
+## Security model
+
+OAuth token bundles (`GH_OAUTH`, `LARK_CLI_OAUTH`) are stored encrypted at rest in
+your vault using the same age-based encryption as other vault entries. They are
+treated as host-only data: the raw JSON bundles are never forwarded into the sandbox
+process environment. Only the derived runtime token (e.g., `GH_TOKEN` for GitHub) is
+injected, so sandbox processes never have access to refresh credentials or OAuth app
+secrets.
diff --git a/docs/content/docs/features/cli-oauth.zh.md b/docs/content/docs/features/cli-oauth.zh.md
new file mode 100644
index 00000000..082e472f
--- /dev/null
+++ b/docs/content/docs/features/cli-oauth.zh.md
@@ -0,0 +1,50 @@
+---
+title: CLI OAuth 认证
+---
+
+## 概述
+
+CLI OAuth 功能允许 Agent 在沙盒会话中直接使用 `gh`（GitHub CLI）和 `lark-cli`，无需手动认证。Anna 在宿主机上完成 OAuth 设备流程，将版本化的令牌包存储到个人密钥库中，并在每次沙盒会话启动时自动注入最新的运行时令牌。
+
+## 前提条件
+
+用户连接前，管理员须在对应的认证插件中配置好应用凭据：
+
+- **GitHub**：管理员需在 GitHub 认证插件设置中填入 OAuth 应用的 Client ID 和 Client Secret。
+- **Lark / 飞书**：管理员需在 Lark 认证插件设置中填入 App ID、App Secret 以及品牌标识（`lark` 或 `feishu`）。
+
+## 连接步骤
+
+1. 打开 Anna 管理面板，进入**个人资料**页面。
+2. 找到 **OAuth CLI 凭据**区域。
+3. 点击要连接的服务商旁边的**连接**按钮。
+4. Anna 启动设备流程，并显示验证 URL 和用户码。
+5. 在浏览器中打开该 URL，输入用户码并完成授权。
+6. Anna 轮询授权结果。授权成功后，令牌包将保存至您的密钥库。
+
+随时可点击服务商旁的**断开连接**取消绑定。
+
+## 使用 CLI 工具
+
+连接成功后，Agent 在沙盒会话中可以直接运行 `gh` 和 `lark-cli` 命令，无需任何额外配置。Anna 会将包装脚本目录添加到 `PATH` 的最前面，使每次调用都自动获得正确的认证凭据。
+
+示例（由 Agent 在 bash 工具调用中执行）：
+
+```sh
+gh issue list --repo owner/repo
+lark-cli message send --chat-id <id> --text "Hello"
+```
+
+## 已知限制
+
+### Lark 令牌有效期
+
+Lark 用户访问令牌有效期约为 **2 小时**。Anna 仅在会话启动时刷新令牌。若 Agent 会话时长超过令牌有效期，`lark-cli` 调用将因认证失败而报错。重新开启一个 Anna 会话，即可自动获取刷新后的令牌。
+
+### 重启会丢失进行中的设备流程
+
+未完成授权的设备流程状态保存在内存中。Anna 进程重启后，这些状态将丢失。如果您正在浏览器中完成授权时 Anna 发生重启，需要在个人资料页面重新发起授权流程。
+
+## 安全模型
+
+OAuth 令牌包（`GH_OAUTH`、`LARK_CLI_OAUTH`）使用与其他密钥库条目相同的 age 加密方式加密存储。它们仅在宿主机上使用：原始 JSON 包不会传入沙盒进程的环境变量。沙盒进程只能获取派生的运行时令牌（例如 GitHub 的 `GH_TOKEN`），无法访问刷新凭据或 OAuth 应用密钥。
diff --git a/docs/content/docs/features/meta.json b/docs/content/docs/features/meta.json
index 485b71ce..4d396450 100644
--- a/docs/content/docs/features/meta.json
+++ b/docs/content/docs/features/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Features",
-  "pages": ["plugin-system", "scheduler-system", "notification-system", "agent-templates", "vault"]
+  "pages": ["plugin-system", "scheduler-system", "notification-system", "agent-templates", "vault", "cli-oauth"]
 }
diff --git a/docs/content/docs/features/meta.zh.json b/docs/content/docs/features/meta.zh.json
index e977c0ec..48e95a85 100644
--- a/docs/content/docs/features/meta.zh.json
+++ b/docs/content/docs/features/meta.zh.json
@@ -1,4 +1,4 @@
 {
   "title": "功能",
-  "pages": ["plugin-system", "scheduler-system", "notification-system", "agent-templates", "vault"]
+  "pages": ["plugin-system", "scheduler-system", "notification-system", "agent-templates", "vault", "cli-oauth"]
 }
diff --git a/internal/agent/runner/sandbox_backend_test.go b/internal/agent/runner/sandbox_backend_test.go
index 0a4e3f85..ff3d0625 100644
--- a/internal/agent/runner/sandbox_backend_test.go
+++ b/internal/agent/runner/sandbox_backend_test.go
@@ -192,3 +192,41 @@ func TestBuildSandboxEnv_noVaultLoader(t *testing.T) {
 		t.Errorf("ANNA_HOME = %q, want %q", got, cfg.AnnaHome)
 	}
 }
+
+// TestBuildSandboxEnv_OAuthBundleKeysStripped verifies that vault entries for
+// the OAuth bundle keys (GH_OAUTH and LARK_CLI_OAUTH) are not forwarded into
+// the sandbox environment, even when present in the vault.
+func TestBuildSandboxEnv_OAuthBundleKeysStripped(t *testing.T) {
+	cfg := GoRunnerConfig{
+		AnnaHome:  "/anna",
+		AgentRoot: "/workspace/agent",
+		UserRoot:  "/workspace/users/1",
+		UserID:    1,
+		VaultEnvLoader: &stubVaultLoader{
+			env: map[string]string{
+				"GH_OAUTH":       `{"version":1,"access_token":"ghp_secret"}`,
+				"LARK_CLI_OAUTH": `{"version":1,"access_token":"u-lark-secret"}`,
+				"OTHER_SECRET":   "should-pass-through",
+			},
+		},
+	}
+
+	paths, err := resolveSandboxPaths(cfg)
+	if err != nil {
+		t.Fatalf("resolveSandboxPaths: %v", err)
+	}
+
+	env := buildSandboxEnv(context.Background(), cfg, paths)
+
+	if _, ok := env["GH_OAUTH"]; ok {
+		t.Error("GH_OAUTH must not appear in sandbox env")
+	}
+	if _, ok := env["LARK_CLI_OAUTH"]; ok {
+		t.Error("LARK_CLI_OAUTH must not appear in sandbox env")
+	}
+
+	// Unrelated vault entries must still pass through.
+	if got := env["OTHER_SECRET"]; got != "should-pass-through" {
+		t.Errorf("OTHER_SECRET = %q, want %q", got, "should-pass-through")
+	}
+}
diff --git a/internal/cliwrap/wrap_test.go b/internal/cliwrap/wrap_test.go
new file mode 100644
index 00000000..85252abe
--- /dev/null
+++ b/internal/cliwrap/wrap_test.go
@@ -0,0 +1,103 @@
+package cliwrap
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestEnsureWrappers_CreatesBinDir(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "newdir", "bin")
+
+	// dir does not exist yet.
+	if _, err := os.Stat(dir); !os.IsNotExist(err) {
+		t.Fatal("expected dir to not exist before EnsureWrappers")
+	}
+
+	if err := EnsureWrappers(dir); err != nil {
+		t.Fatalf("EnsureWrappers: %v", err)
+	}
+
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("Stat after EnsureWrappers: %v", err)
+	}
+	if !info.IsDir() {
+		t.Fatal("expected binDir to be a directory")
+	}
+}
+
+func TestEnsureWrappers_WritesGhScript(t *testing.T) {
+	dir := t.TempDir()
+
+	if err := EnsureWrappers(dir); err != nil {
+		t.Fatalf("EnsureWrappers: %v", err)
+	}
+
+	data, err := os.ReadFile(filepath.Join(dir, "gh"))
+	if err != nil {
+		t.Fatalf("ReadFile gh: %v", err)
+	}
+	content := string(data)
+	if !strings.HasPrefix(content, "#!/bin/sh") {
+		t.Errorf("gh wrapper does not start with #!/bin/sh, got: %q", content[:min(len(content), 20)])
+	}
+}
+
+func TestEnsureWrappers_WritesLarkCliScript(t *testing.T) {
+	dir := t.TempDir()
+
+	if err := EnsureWrappers(dir); err != nil {
+		t.Fatalf("EnsureWrappers: %v", err)
+	}
+
+	data, err := os.ReadFile(filepath.Join(dir, "lark-cli"))
+	if err != nil {
+		t.Fatalf("ReadFile lark-cli: %v", err)
+	}
+	content := string(data)
+	if !strings.HasPrefix(content, "#!/bin/sh") {
+		t.Errorf("lark-cli wrapper does not start with #!/bin/sh, got: %q", content[:min(len(content), 20)])
+	}
+}
+
+func TestEnsureWrappers_ScriptsAreExecutable(t *testing.T) {
+	dir := t.TempDir()
+
+	if err := EnsureWrappers(dir); err != nil {
+		t.Fatalf("EnsureWrappers: %v", err)
+	}
+
+	for _, name := range []string{"gh", "lark-cli"} {
+		info, err := os.Stat(filepath.Join(dir, name))
+		if err != nil {
+			t.Fatalf("Stat %s: %v", name, err)
+		}
+		if info.Mode()&0o111 == 0 {
+			t.Errorf("%s is not executable (mode %o)", name, info.Mode())
+		}
+	}
+}
+
+func TestEnsureWrappers_Idempotent(t *testing.T) {
+	dir := t.TempDir()
+
+	if err := EnsureWrappers(dir); err != nil {
+		t.Fatalf("EnsureWrappers (first call): %v", err)
+	}
+	if err := EnsureWrappers(dir); err != nil {
+		t.Fatalf("EnsureWrappers (second call): %v", err)
+	}
+
+	// Content should be identical on both calls.
+	for _, name := range []string{"gh", "lark-cli"} {
+		data, err := os.ReadFile(filepath.Join(dir, name))
+		if err != nil {
+			t.Fatalf("ReadFile %s: %v", name, err)
+		}
+		if !strings.HasPrefix(string(data), "#!/bin/sh") {
+			t.Errorf("%s wrapper corrupt after second call", name)
+		}
+	}
+}
diff --git a/internal/oauthcli/store_test.go b/internal/oauthcli/store_test.go
new file mode 100644
index 00000000..7e4d8b6b
--- /dev/null
+++ b/internal/oauthcli/store_test.go
@@ -0,0 +1,108 @@
+package oauthcli
+
+import (
+	"testing"
+	"time"
+)
+
+func TestFlowStore_CreateAndGet(t *testing.T) {
+	s := NewFlowStore()
+	flow := FlowStatus{
+		Provider:        ProviderGitHub,
+		FlowID:          "flow-1",
+		VerificationURI: "https://github.com/login/device",
+		UserCode:        "ABCD-1234",
+		ExpiresAt:       time.Now().Add(15 * time.Minute),
+		State:           FlowStatePending,
+	}
+
+	s.Create(flow)
+
+	got, ok := s.Get("flow-1")
+	if !ok {
+		t.Fatal("Get: expected flow to exist")
+	}
+	if got.FlowID != flow.FlowID {
+		t.Errorf("FlowID = %q, want %q", got.FlowID, flow.FlowID)
+	}
+	if got.State != FlowStatePending {
+		t.Errorf("State = %q, want %q", got.State, FlowStatePending)
+	}
+	if got.VerificationURI != flow.VerificationURI {
+		t.Errorf("VerificationURI = %q, want %q", got.VerificationURI, flow.VerificationURI)
+	}
+}
+
+func TestFlowStore_GetMissing(t *testing.T) {
+	s := NewFlowStore()
+	_, ok := s.Get("nonexistent")
+	if ok {
+		t.Fatal("Get: expected false for missing flow")
+	}
+}
+
+func TestFlowStore_Update(t *testing.T) {
+	s := NewFlowStore()
+	s.Create(FlowStatus{
+		FlowID: "flow-2",
+		State:  FlowStatePending,
+	})
+
+	s.Update("flow-2", FlowStateAuthorized, nil)
+
+	got, ok := s.Get("flow-2")
+	if !ok {
+		t.Fatal("Get after Update: expected flow to exist")
+	}
+	if got.State != FlowStateAuthorized {
+		t.Errorf("State = %q, want %q", got.State, FlowStateAuthorized)
+	}
+}
+
+func TestFlowStore_UpdateWithMutator(t *testing.T) {
+	s := NewFlowStore()
+	s.Create(FlowStatus{
+		FlowID: "flow-3",
+		State:  FlowStatePending,
+	})
+
+	sentinel := "verified-code"
+	s.Update("flow-3", FlowStateAuthorized, func(fs *FlowStatus) {
+		fs.UserCode = sentinel
+	})
+
+	got, ok := s.Get("flow-3")
+	if !ok {
+		t.Fatal("Get: expected flow to exist")
+	}
+	if got.State != FlowStateAuthorized {
+		t.Errorf("State = %q, want %q", got.State, FlowStateAuthorized)
+	}
+	if got.UserCode != sentinel {
+		t.Errorf("UserCode = %q, want %q", got.UserCode, sentinel)
+	}
+}
+
+func TestFlowStore_UpdateMissingIsNoOp(t *testing.T) {
+	s := NewFlowStore()
+	// Should not panic.
+	s.Update("no-such-flow", FlowStateFailed, nil)
+}
+
+func TestFlowStore_Delete(t *testing.T) {
+	s := NewFlowStore()
+	s.Create(FlowStatus{FlowID: "flow-del", State: FlowStatePending})
+
+	s.Delete("flow-del")
+
+	_, ok := s.Get("flow-del")
+	if ok {
+		t.Fatal("Get after Delete: expected flow to be absent")
+	}
+}
+
+func TestFlowStore_DeleteMissingIsNoOp(t *testing.T) {
+	s := NewFlowStore()
+	// Should not panic.
+	s.Delete("not-there")
+}
diff --git a/internal/oauthcli/vault_test.go b/internal/oauthcli/vault_test.go
new file mode 100644
index 00000000..e5767e16
--- /dev/null
+++ b/internal/oauthcli/vault_test.go
@@ -0,0 +1,182 @@
+package oauthcli
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+)
+
+// mockVaultStore is a simple in-memory VaultStore for testing.
+type mockVaultStore struct {
+	data map[string]string // keyed by "userID:name"
+}
+
+func newMockVaultStore() *mockVaultStore {
+	return &mockVaultStore{data: make(map[string]string)}
+}
+
+func (m *mockVaultStore) key(userID int64, name string) string {
+	return fmt.Sprintf("%d:%s", userID, name)
+}
+
+func (m *mockVaultStore) Set(_ context.Context, userID int64, name string, plaintext string) error {
+	m.data[m.key(userID, name)] = plaintext
+	return nil
+}
+
+func (m *mockVaultStore) Delete(_ context.Context, userID int64, name string) error {
+	delete(m.data, m.key(userID, name))
+	return nil
+}
+
+func (m *mockVaultStore) LoadEnv(_ context.Context, userID int64) (map[string]string, error) {
+	out := make(map[string]string)
+	prefix := fmt.Sprintf("%d:", userID)
+	for k, v := range m.data {
+		if len(k) > len(prefix) && k[:len(prefix)] == prefix {
+			name := k[len(prefix):]
+			out[name] = v
+		}
+	}
+	return out, nil
+}
+
+func TestSaveLoadGHBundle_RoundTrip(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(1)
+
+	expiry := time.Date(2030, 1, 1, 0, 0, 0, 0, time.UTC)
+	bundle := GHOAuthBundle{
+		Version:     1,
+		AccessToken: "ghp_test_token",
+		TokenType:   "bearer",
+		Scope:       "repo,read:org",
+		ExpiresAt:   &expiry,
+	}
+
+	if err := SaveGHBundle(ctx, vs, userID, bundle); err != nil {
+		t.Fatalf("SaveGHBundle: %v", err)
+	}
+
+	got, err := LoadGHBundle(ctx, vs, userID)
+	if err != nil {
+		t.Fatalf("LoadGHBundle: %v", err)
+	}
+	if got == nil {
+		t.Fatal("LoadGHBundle: expected non-nil bundle")
+	}
+	if got.AccessToken != bundle.AccessToken {
+		t.Errorf("AccessToken = %q, want %q", got.AccessToken, bundle.AccessToken)
+	}
+	if got.TokenType != bundle.TokenType {
+		t.Errorf("TokenType = %q, want %q", got.TokenType, bundle.TokenType)
+	}
+	if got.Scope != bundle.Scope {
+		t.Errorf("Scope = %q, want %q", got.Scope, bundle.Scope)
+	}
+	if got.Version != bundle.Version {
+		t.Errorf("Version = %d, want %d", got.Version, bundle.Version)
+	}
+	if got.ExpiresAt == nil || !got.ExpiresAt.Equal(*bundle.ExpiresAt) {
+		t.Errorf("ExpiresAt = %v, want %v", got.ExpiresAt, bundle.ExpiresAt)
+	}
+}
+
+func TestLoadGHBundle_AbsentKeyReturnsNil(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+
+	got, err := LoadGHBundle(ctx, vs, 42)
+	if err != nil {
+		t.Fatalf("LoadGHBundle: unexpected error: %v", err)
+	}
+	if got != nil {
+		t.Errorf("LoadGHBundle: expected nil for absent key, got %+v", got)
+	}
+}
+
+func TestSaveLoadLarkBundle_RoundTrip(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(2)
+
+	now := time.Now().UTC().Truncate(time.Second)
+	bundle := LarkOAuthBundle{
+		Version:          1,
+		AppID:            "cli_test_app_id",
+		AppSecret:        "cli_test_app_secret",
+		Brand:            "lark",
+		AccessToken:      "u-test-access-token",
+		RefreshToken:     "u-test-refresh-token",
+		AccessExpiresAt:  now.Add(2 * time.Hour),
+		RefreshExpiresAt: now.Add(30 * 24 * time.Hour),
+	}
+
+	if err := SaveLarkBundle(ctx, vs, userID, bundle); err != nil {
+		t.Fatalf("SaveLarkBundle: %v", err)
+	}
+
+	got, err := LoadLarkBundle(ctx, vs, userID)
+	if err != nil {
+		t.Fatalf("LoadLarkBundle: %v", err)
+	}
+	if got == nil {
+		t.Fatal("LoadLarkBundle: expected non-nil bundle")
+	}
+	if got.AppID != bundle.AppID {
+		t.Errorf("AppID = %q, want %q", got.AppID, bundle.AppID)
+	}
+	if got.AppSecret != bundle.AppSecret {
+		t.Errorf("AppSecret = %q, want %q", got.AppSecret, bundle.AppSecret)
+	}
+	if got.Brand != bundle.Brand {
+		t.Errorf("Brand = %q, want %q", got.Brand, bundle.Brand)
+	}
+	if got.AccessToken != bundle.AccessToken {
+		t.Errorf("AccessToken = %q, want %q", got.AccessToken, bundle.AccessToken)
+	}
+	if got.RefreshToken != bundle.RefreshToken {
+		t.Errorf("RefreshToken = %q, want %q", got.RefreshToken, bundle.RefreshToken)
+	}
+	if !got.AccessExpiresAt.Equal(bundle.AccessExpiresAt) {
+		t.Errorf("AccessExpiresAt = %v, want %v", got.AccessExpiresAt, bundle.AccessExpiresAt)
+	}
+}
+
+func TestLoadLarkBundle_AbsentKeyReturnsNil(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+
+	got, err := LoadLarkBundle(ctx, vs, 99)
+	if err != nil {
+		t.Fatalf("LoadLarkBundle: unexpected error: %v", err)
+	}
+	if got != nil {
+		t.Errorf("LoadLarkBundle: expected nil for absent key, got %+v", got)
+	}
+}
+
+func TestDeleteBundle(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(3)
+
+	bundle := GHOAuthBundle{Version: 1, AccessToken: "ghp_todelete"}
+	if err := SaveGHBundle(ctx, vs, userID, bundle); err != nil {
+		t.Fatalf("SaveGHBundle: %v", err)
+	}
+
+	if err := DeleteBundle(ctx, vs, userID, VaultKeyGitHub); err != nil {
+		t.Fatalf("DeleteBundle: %v", err)
+	}
+
+	got, err := LoadGHBundle(ctx, vs, userID)
+	if err != nil {
+		t.Fatalf("LoadGHBundle after delete: %v", err)
+	}
+	if got != nil {
+		t.Errorf("LoadGHBundle after delete: expected nil, got %+v", got)
+	}
+}
diff --git a/internal/resources/skills/system/anna/SKILL.md b/internal/resources/skills/system/anna/SKILL.md
index 582d0fae..795570fa 100644
--- a/internal/resources/skills/system/anna/SKILL.md
+++ b/internal/resources/skills/system/anna/SKILL.md
@@ -122,5 +122,6 @@ These are tools you already have access to. Briefly:
 - **Notifications**: `notify` tool (gateway mode only) -- send messages via Telegram/QQ/Feishu/WeChat dispatcher.
 - **Session compaction**: auto-triggers at 80k tokens, or manually via `/compact`. Configurable in settings.
 - **Managed helper CLIs**: The `bash` tool prepends Anna-managed binaries to `PATH`. Expect `fd`, `rg`, `mise`, and `tap` to be available even when the host machine doesn't have them installed separately.
+- **CLI OAuth (`gh` and `lark-cli`)**: When the user has connected their GitHub or Lark account via Profile → OAuth CLI Credentials, `gh` and `lark-cli` work directly in `bash` tool calls without any manual auth step. Anna injects a fresh runtime token at session start. Note: Lark user access tokens expire after ~2 hours; start a new session to refresh. If the user has not connected, `gh` and `lark-cli` are still on `PATH` but will require manual authentication.
 - **Plugins**: Anna now uses a unified plugin host. A plugin owns its config, runtime lifecycle, status, and capability registrations. Built-in capabilities currently cover tools (`mcp`, `webfetch`), channels (telegram, qq, feishu, weixin), hooks (trace, rtk), providers (anthropic, openai, openai-response), memory (`lcm`, `simple`), and the standalone reflect runtime. Core tools (read/bash/edit/write/agent/memory/scheduler/skills) are always enabled and are not plugins. The `mcp` plugin lets admins configure multiple MCP servers/transports in the admin UI, reconciles its runtime through the plugin host, exposes one generic `mcp` tool, and contributes structured prompt inventory for discovered MCP tool IDs. The `reflect` plugin also reconciles its background review loop through the host while keeping the existing `reflect` settings row. The `telegram`, `qq`, `feishu`, and `weixin` channels all use the same host-backed config/runtime/status path while keeping their existing `channel/...` rows and `/channels` admin UX. When using MCP tools, inspect prompt-listed MCP tool IDs and always call `mcp` with `action="get"` before `action="exec"`. Manage plugins with `anna plugin list/enable/disable/config`.
 - **Trace hook**: The `trace` hook logs all LLM calls, tool executions, and memory operations via slog. Set `OTEL_EXPORTER_OTLP_ENDPOINT` to also export OpenTelemetry traces using standard OTel env vars. Both OTLP/gRPC and OTLP/HTTP are supported, including auth headers via `OTEL_EXPORTER_OTLP_HEADERS` or `OTEL_EXPORTER_OTLP_TRACES_HEADERS`. Always include a scheme in the endpoint (for example `http://localhost:4317` or `https://collector.example.com/api/default`). No code changes needed -- just set the env vars and restart.
diff --git a/plugins/sandbox/docker/session_pure_test.go b/plugins/sandbox/docker/session_pure_test.go
index 39011957..cf096a8d 100644
--- a/plugins/sandbox/docker/session_pure_test.go
+++ b/plugins/sandbox/docker/session_pure_test.go
@@ -63,3 +63,80 @@ func TestMapNetworkMode(t *testing.T) {
 		}
 	}
 }
+
+func TestInjectWrapperPath_PrependedWhenSet(t *testing.T) {
+	env := map[string]string{
+		"ANNA_WRAPPER_DIR": "/home/anna/workspace/.anna/bin",
+		"PATH":             "/usr/bin:/bin",
+	}
+	got := injectWrapperPath(env)
+	want := "/home/anna/workspace/.anna/bin:/usr/bin:/bin"
+	if got["PATH"] != want {
+		t.Errorf("PATH = %q, want %q", got["PATH"], want)
+	}
+}
+
+func TestInjectWrapperPath_UsesDefaultPathWhenPATHAbsent(t *testing.T) {
+	env := map[string]string{
+		"ANNA_WRAPPER_DIR": "/home/anna/workspace/.anna/bin",
+	}
+	got := injectWrapperPath(env)
+	if got["PATH"] == "" {
+		t.Fatal("PATH should not be empty when ANNA_WRAPPER_DIR is set")
+	}
+	if got["PATH"][:len("/home/anna/workspace/.anna/bin:")] != "/home/anna/workspace/.anna/bin:" {
+		t.Errorf("PATH does not start with wrapper dir: %q", got["PATH"])
+	}
+	// Should include the container default PATH.
+	if len(got["PATH"]) <= len("/home/anna/workspace/.anna/bin:") {
+		t.Error("PATH should include containerDefaultPATH after wrapper dir")
+	}
+}
+
+func TestInjectWrapperPath_NoOpWhenAbsent(t *testing.T) {
+	env := map[string]string{
+		"PATH": "/usr/bin:/bin",
+	}
+	got := injectWrapperPath(env)
+	if got["PATH"] != "/usr/bin:/bin" {
+		t.Errorf("PATH changed when ANNA_WRAPPER_DIR absent: %q", got["PATH"])
+	}
+}
+
+func TestInjectWrapperPath_NoOpWhenEmpty(t *testing.T) {
+	env := map[string]string{
+		"ANNA_WRAPPER_DIR": "",
+		"PATH":             "/usr/bin:/bin",
+	}
+	got := injectWrapperPath(env)
+	if got["PATH"] != "/usr/bin:/bin" {
+		t.Errorf("PATH changed when ANNA_WRAPPER_DIR is empty: %q", got["PATH"])
+	}
+}
+
+func TestInjectDockerBinPaths_SetsFixedPaths(t *testing.T) {
+	env := map[string]string{}
+	got := injectDockerBinPaths(env)
+
+	if got["ANNA_GH_BIN"] != "/usr/bin/gh" {
+		t.Errorf("ANNA_GH_BIN = %q, want %q", got["ANNA_GH_BIN"], "/usr/bin/gh")
+	}
+	if got["ANNA_LARK_BIN"] != "/usr/local/bin/lark-cli" {
+		t.Errorf("ANNA_LARK_BIN = %q, want %q", got["ANNA_LARK_BIN"], "/usr/local/bin/lark-cli")
+	}
+}
+
+func TestInjectDockerBinPaths_OverridesHostPaths(t *testing.T) {
+	env := map[string]string{
+		"ANNA_GH_BIN":   "/host/anna/bin/gh",
+		"ANNA_LARK_BIN": "/host/anna/bin/lark-cli",
+	}
+	got := injectDockerBinPaths(env)
+
+	if got["ANNA_GH_BIN"] != "/usr/bin/gh" {
+		t.Errorf("ANNA_GH_BIN = %q, want container path %q", got["ANNA_GH_BIN"], "/usr/bin/gh")
+	}
+	if got["ANNA_LARK_BIN"] != "/usr/local/bin/lark-cli" {
+		t.Errorf("ANNA_LARK_BIN = %q, want container path %q", got["ANNA_LARK_BIN"], "/usr/local/bin/lark-cli")
+	}
+}

From 001768935181756d61ff256e7d288c2027407f9c Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 08:54:03 +0800
Subject: [PATCH 07/21] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20remove?=
 =?UTF-8?q?=20hardcoded=20gh=20and=20lark-cli=20from=20dockerfile?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move gh and lark-cli installation from Dockerfile to mise-managed tools
in _mise.toml for better version flexibility and consistency.
---
 plugins/sandbox/docker/Dockerfile | 27 ---------------------------
 plugins/sandbox/docker/_mise.toml |  2 ++
 2 files changed, 2 insertions(+), 27 deletions(-)

diff --git a/plugins/sandbox/docker/Dockerfile b/plugins/sandbox/docker/Dockerfile
index f75a9e10..bfabae42 100644
--- a/plugins/sandbox/docker/Dockerfile
+++ b/plugins/sandbox/docker/Dockerfile
@@ -24,33 +24,6 @@ RUN apt-get update && \
     ln -s /usr/bin/fdfind /usr/local/bin/fd && \
     apt-get clean && rm -rf /var/lib/apt/lists/*
 
-# GitHub CLI (gh) — version pinned to match internal/builddeps/binaries.go ghCLIVersion
-RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
-        | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && \
-    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
-        | tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
-    apt-get update && \
-    apt-get install -y gh=2.89.0 && \
-    apt-get clean && rm -rf /var/lib/apt/lists/*
-
-# lark-cli — version pinned to match internal/builddeps/binaries.go larkCLIVersion
-# Released as a tarball from github.com/larksuite/cli at /usr/local/bin/lark-cli
-# (injectDockerBinPaths in plugins/sandbox/docker/session.go relies on this path)
-ARG LARK_CLI_VERSION=1.0.15
-RUN set -eux; \
-    ARCH="$(dpkg --print-architecture)"; \
-    case "$ARCH" in \
-        amd64) LARK_ARCH="linux-amd64" ;; \
-        arm64) LARK_ARCH="linux-arm64" ;; \
-        *) echo "unsupported architecture: $ARCH" >&2; exit 1 ;; \
-    esac; \
-    curl -fsSL \
-        "https://github.com/larksuite/cli/releases/download/v${LARK_CLI_VERSION}/lark-cli-${LARK_CLI_VERSION}-${LARK_ARCH}.tar.gz" \
-        -o /tmp/lark-cli.tar.gz && \
-    tar -xzf /tmp/lark-cli.tar.gz -C /tmp && \
-    find /tmp -name "lark-cli" -type f -exec install -m 755 {} /usr/local/bin/lark-cli \; && \
-    rm -f /tmp/lark-cli.tar.gz
-
 ARG USER_UID=1000
 ARG USER_GID=1000
 
diff --git a/plugins/sandbox/docker/_mise.toml b/plugins/sandbox/docker/_mise.toml
index 5fb082d9..90c0fa30 100644
--- a/plugins/sandbox/docker/_mise.toml
+++ b/plugins/sandbox/docker/_mise.toml
@@ -10,6 +10,8 @@ LIBUNWIND_PRINT_DWARF = "0"
 UV_PYTHON = "/usr/bin/python3"
 
 [tools]
+gh = "latest"
 "github:vaayne/tap" = "latest"
 "github:rtk-ai/rtk" = "latest"
 "github:xicilion/boxsh" = "latest"
+"github:larksuite/cli" = "latest"

From e11c4b627816a000b839f927710ce06f6a764357 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 08:54:08 +0800
Subject: [PATCH 08/21] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor(oauthcli):?=
 =?UTF-8?q?=20use=20golang.org/x/oauth2=20for=20GitHub=20device=20flow=20a?=
 =?UTF-8?q?nd=20Lark=20auth=20URL?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace hand-rolled HTTP for GitHub device flow with oauth2.Config + github.Endpoint.
StartDeviceFlow spawns a background goroutine running cfg.DeviceAccessToken; Poll reads
FlowStore state without making HTTP calls. Lark auth URL now built via oauth2.Config.AuthCodeURL;
token exchange and refresh stay as custom HTTP (Lark requires Bearer app_access_token header).
Extract postJSON helper to http.go.

Assisted-by: claude-code:claude-sonnet-4-6
---
 internal/oauthcli/gh.go   | 258 +++++++++++---------------------------
 internal/oauthcli/http.go |  34 +++++
 internal/oauthcli/lark.go |  44 ++++---
 3 files changed, 127 insertions(+), 209 deletions(-)
 create mode 100644 internal/oauthcli/http.go

diff --git a/internal/oauthcli/gh.go b/internal/oauthcli/gh.go
index 1de2f84e..417d3af3 100644
--- a/internal/oauthcli/gh.go
+++ b/internal/oauthcli/gh.go
@@ -1,24 +1,17 @@
 package oauthcli
 
 import (
-	"bytes"
 	"context"
-	"encoding/json"
 	"fmt"
-	"net/http"
-	"net/url"
-	"strings"
 	"sync"
 	"time"
 
 	"github.com/google/uuid"
+	"golang.org/x/oauth2"
+	"golang.org/x/oauth2/github"
 )
 
-const (
-	ghDeviceCodeURL  = "https://github.com/login/device/code"
-	ghAccessTokenURL = "https://github.com/login/oauth/access_token"
-	ghScope          = "repo,read:org"
-)
+const ghScope = "repo,read:org"
 
 // GitHubConfig holds the OAuth app credentials for device flow.
 type GitHubConfig struct {
@@ -26,11 +19,12 @@ type GitHubConfig struct {
 	ClientSecret string
 }
 
-// ghFlowSecret holds provider-specific secrets for an in-flight GitHub flow.
+// ghFlowSecret holds in-flight state for a GitHub device flow.
 type ghFlowSecret struct {
-	deviceCode string
-	interval   int // seconds between polls, as returned by GitHub
-	bundle     *GHOAuthBundle
+	cancel context.CancelFunc
+	token  *oauth2.Token
+	err    error
+	done   chan struct{}
 }
 
 // GitHubBroker manages GitHub device-flow sessions.
@@ -50,87 +44,71 @@ func NewGitHubBroker(cfg GitHubConfig, store *FlowStore) *GitHubBroker {
 	}
 }
 
-// ghDeviceCodeResponse is the JSON body from POST /login/device/code.
-type ghDeviceCodeResponse struct {
-	DeviceCode      string `json:"device_code"`
-	UserCode        string `json:"user_code"`
-	VerificationURI string `json:"verification_uri"`
-	ExpiresIn       int    `json:"expires_in"`
-	Interval        int    `json:"interval"`
-}
-
-// ghAccessTokenResponse is the JSON body from POST /login/oauth/access_token.
-type ghAccessTokenResponse struct {
-	AccessToken string `json:"access_token"`
-	TokenType   string `json:"token_type"`
-	Scope       string `json:"scope"`
-	Error       string `json:"error"`
-	// Fine-grained tokens may carry expiry.
-	ExpiresIn    int    `json:"expires_in,omitempty"`
-	RefreshToken string `json:"refresh_token,omitempty"`
+func (b *GitHubBroker) oauthConfig() *oauth2.Config {
+	return &oauth2.Config{
+		ClientID:     b.cfg.ClientID,
+		ClientSecret: b.cfg.ClientSecret,
+		Scopes:       []string{ghScope},
+		Endpoint:     github.Endpoint,
+	}
 }
 
 // StartDeviceFlow requests a device code from GitHub, stores pending state,
 // and returns the FlowStatus the caller should display to the user.
+// A background goroutine polls GitHub until the user authorizes or the flow expires.
 func (b *GitHubBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowStatus, error) {
-	body := url.Values{}
-	body.Set("client_id", b.cfg.ClientID)
-	body.Set("scope", ghScope)
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, ghDeviceCodeURL,
-		strings.NewReader(body.Encode()))
-	if err != nil {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: build device code request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Accept", "application/json")
+	cfg := b.oauthConfig()
 
-	resp, err := http.DefaultClient.Do(req)
+	da, err := cfg.DeviceAuth(ctx, oauth2.AccessTypeOnline)
 	if err != nil {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: device code request: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusOK {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: device code: unexpected status %d", resp.StatusCode)
-	}
-
-	var dc ghDeviceCodeResponse
-	if err := json.NewDecoder(resp.Body).Decode(&dc); err != nil {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: decode device code response: %w", err)
-	}
-
-	if dc.Interval <= 0 {
-		dc.Interval = 5 // GitHub default
+		return FlowStatus{}, fmt.Errorf("oauthcli/gh: device auth: %w", err)
 	}
 
 	flowID := uuid.NewString()
-	expiresAt := time.Now().Add(time.Duration(dc.ExpiresIn) * time.Second)
+	expiresAt := da.Expiry
 
 	status := FlowStatus{
 		Provider:        ProviderGitHub,
 		FlowID:          flowID,
-		VerificationURI: dc.VerificationURI,
-		UserCode:        dc.UserCode,
+		VerificationURI: da.VerificationURIComplete,
+		UserCode:        da.UserCode,
 		ExpiresAt:       expiresAt,
 		State:           FlowStatePending,
 	}
+	if status.VerificationURI == "" {
+		status.VerificationURI = da.VerificationURI
+	}
 
 	b.store.Create(status)
 
-	b.mu.Lock()
-	b.secret[flowID] = &ghFlowSecret{
-		deviceCode: dc.DeviceCode,
-		interval:   dc.Interval,
+	bgCtx, cancel := context.WithDeadline(context.Background(), expiresAt)
+	sec := &ghFlowSecret{
+		cancel: cancel,
+		done:   make(chan struct{}),
 	}
+	b.mu.Lock()
+	b.secret[flowID] = sec
 	b.mu.Unlock()
 
+	go func() {
+		defer close(sec.done)
+		tok, err := cfg.DeviceAccessToken(bgCtx, da)
+		b.mu.Lock()
+		sec.token = tok
+		sec.err = err
+		b.mu.Unlock()
+		if err == nil {
+			b.store.Update(flowID, FlowStateAuthorized, nil)
+		} else {
+			b.store.Update(flowID, FlowStateFailed, nil)
+		}
+	}()
+
 	return status, nil
 }
 
 // Poll checks whether the user has completed authorization for flowID.
-// It updates the store state and returns the current FlowStatus.
-// Callers must call Complete after Poll returns State == FlowStateAuthorized.
+// It reads from the store — the background goroutine updates it when done.
 func (b *GitHubBroker) Poll(ctx context.Context, flowID string) (FlowStatus, error) {
 	status, ok := b.store.Get(flowID)
 	if !ok {
@@ -148,103 +126,44 @@ func (b *GitHubBroker) Poll(ctx context.Context, flowID string) (FlowStatus, err
 		return status, nil
 	}
 
+	return status, nil
+}
+
+// Complete persists the token bundle to vault. Must be called only after Poll
+// returns State == FlowStateAuthorized.
+func (b *GitHubBroker) Complete(ctx context.Context, vs VaultStore, userID int64, flowID string) error {
 	b.mu.Lock()
 	sec, ok := b.secret[flowID]
 	b.mu.Unlock()
 	if !ok {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: missing secrets for flow %q", flowID)
+		return fmt.Errorf("oauthcli/gh: no authorized token for flow %q", flowID)
 	}
 
-	reqBody := url.Values{}
-	reqBody.Set("client_id", b.cfg.ClientID)
-	reqBody.Set("device_code", sec.deviceCode)
-	reqBody.Set("grant_type", "urn:ietf:params:oauth:grant-type:device_code")
+	// Wait for the background goroutine to finish if it hasn't yet.
+	<-sec.done
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, ghAccessTokenURL,
-		strings.NewReader(reqBody.Encode()))
-	if err != nil {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: build poll request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Accept", "application/json")
+	b.mu.Lock()
+	tok := sec.token
+	err := sec.err
+	b.mu.Unlock()
 
-	resp, err := http.DefaultClient.Do(req)
 	if err != nil {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: poll request: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	var at ghAccessTokenResponse
-	if err := json.NewDecoder(resp.Body).Decode(&at); err != nil {
-		return FlowStatus{}, fmt.Errorf("oauthcli/gh: decode poll response: %w", err)
+		return fmt.Errorf("oauthcli/gh: flow %q failed: %w", flowID, err)
 	}
-
-	switch at.Error {
-	case "":
-		// Success — stash the token bundle, mark authorized.
-		bundle := &GHOAuthBundle{
-			Version:      1,
-			AccessToken:  at.AccessToken,
-			TokenType:    at.TokenType,
-			Scope:        at.Scope,
-			RefreshToken: at.RefreshToken,
-		}
-		if at.ExpiresIn > 0 {
-			t := time.Now().Add(time.Duration(at.ExpiresIn) * time.Second)
-			bundle.ExpiresAt = &t
-		}
-		b.mu.Lock()
-		sec.bundle = bundle
-		b.mu.Unlock()
-		b.store.Update(flowID, FlowStateAuthorized, nil)
-		status.State = FlowStateAuthorized
-		return status, nil
-
-	case "authorization_pending":
-		// Still waiting — no change.
-		return status, nil
-
-	case "slow_down":
-		// GitHub wants us to back off; bump the stored interval and keep waiting.
-		b.mu.Lock()
-		sec.interval += 5
-		b.mu.Unlock()
-		return status, nil
-
-	case "expired_token":
-		b.store.Update(flowID, FlowStateExpired, nil)
-		b.cleanSecret(flowID)
-		status.State = FlowStateExpired
-		return status, nil
-
-	case "access_denied":
-		b.store.Update(flowID, FlowStateFailed, nil)
-		b.cleanSecret(flowID)
-		status.State = FlowStateFailed
-		return status, fmt.Errorf("oauthcli/gh: access denied by user")
-
-	default:
-		b.store.Update(flowID, FlowStateFailed, nil)
-		b.cleanSecret(flowID)
-		status.State = FlowStateFailed
-		return status, fmt.Errorf("oauthcli/gh: unexpected error %q from GitHub", at.Error)
+	if tok == nil {
+		return fmt.Errorf("oauthcli/gh: flow %q is not yet authorized", flowID)
 	}
-}
 
-// Complete persists the token bundle to vault. Must be called only after Poll
-// returns State == FlowStateAuthorized.
-func (b *GitHubBroker) Complete(ctx context.Context, vs VaultStore, userID int64, flowID string) error {
-	b.mu.Lock()
-	sec, ok := b.secret[flowID]
-	b.mu.Unlock()
-	if !ok {
-		return fmt.Errorf("oauthcli/gh: no authorized token for flow %q", flowID)
+	bundle := GHOAuthBundle{
+		Version:     1,
+		AccessToken: tok.AccessToken,
+		TokenType:   tok.TokenType,
 	}
-	if sec.bundle == nil {
-		return fmt.Errorf("oauthcli/gh: flow %q is not yet authorized", flowID)
+	if !tok.Expiry.IsZero() {
+		bundle.ExpiresAt = &tok.Expiry
 	}
 
-	if err := SaveGHBundle(ctx, vs, userID, *sec.bundle); err != nil {
+	if err := SaveGHBundle(ctx, vs, userID, bundle); err != nil {
 		return err
 	}
 
@@ -253,44 +172,11 @@ func (b *GitHubBroker) Complete(ctx context.Context, vs VaultStore, userID int64
 	return nil
 }
 
-// PollInterval returns the current recommended seconds-between-polls for a
-// flow. Returns 5 (GitHub default) if the flow is unknown.
-func (b *GitHubBroker) PollInterval(flowID string) int {
+func (b *GitHubBroker) cleanSecret(flowID string) {
 	b.mu.Lock()
-	defer b.mu.Unlock()
 	if sec, ok := b.secret[flowID]; ok {
-		return sec.interval
+		sec.cancel()
+		delete(b.secret, flowID)
 	}
-	return 5
-}
-
-func (b *GitHubBroker) cleanSecret(flowID string) {
-	b.mu.Lock()
-	delete(b.secret, flowID)
 	b.mu.Unlock()
 }
-
-// postJSON is a small helper to POST a JSON body and decode the response.
-func postJSON(ctx context.Context, url string, reqBody any, headers map[string]string, out any) error {
-	data, err := json.Marshal(reqBody)
-	if err != nil {
-		return fmt.Errorf("marshal request: %w", err)
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(data))
-	if err != nil {
-		return fmt.Errorf("build request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json; charset=utf-8")
-	for k, v := range headers {
-		req.Header.Set(k, v)
-	}
-	resp, err := http.DefaultClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("do request: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return fmt.Errorf("unexpected status %d", resp.StatusCode)
-	}
-	return json.NewDecoder(resp.Body).Decode(out)
-}
diff --git a/internal/oauthcli/http.go b/internal/oauthcli/http.go
new file mode 100644
index 00000000..3e653608
--- /dev/null
+++ b/internal/oauthcli/http.go
@@ -0,0 +1,34 @@
+package oauthcli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+)
+
+// postJSON POSTs a JSON body and decodes the JSON response into out.
+func postJSON(ctx context.Context, url string, reqBody any, headers map[string]string, out any) error {
+	data, err := json.Marshal(reqBody)
+	if err != nil {
+		return fmt.Errorf("marshal request: %w", err)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(data))
+	if err != nil {
+		return fmt.Errorf("build request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json; charset=utf-8")
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("do request: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("unexpected status %d", resp.StatusCode)
+	}
+	return json.NewDecoder(resp.Body).Decode(out)
+}
diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
index d2c25d33..da573c57 100644
--- a/internal/oauthcli/lark.go
+++ b/internal/oauthcli/lark.go
@@ -3,11 +3,11 @@ package oauthcli
 import (
 	"context"
 	"fmt"
-	"net/url"
 	"sync"
 	"time"
 
 	"github.com/google/uuid"
+	"golang.org/x/oauth2"
 )
 
 const (
@@ -15,6 +15,7 @@ const (
 	larkBaseLark   = "https://open.larksuite.com"
 
 	larkRedirectURI = "https://anna.app/oauth/lark/callback" // placeholder; caller sets up the real redirect
+	larkScope       = "contact:user.base:readonly"
 )
 
 // LarkConfig holds the OAuth app credentials for Lark/Feishu device-style flow.
@@ -71,16 +72,26 @@ func (b *LarkBroker) baseURL() string {
 	return larkBaseLark
 }
 
+func (b *LarkBroker) oauthConfig() *oauth2.Config {
+	base := b.baseURL()
+	return &oauth2.Config{
+		ClientID:    b.cfg.AppID,
+		RedirectURL: b.redirectURI,
+		Scopes:      []string{larkScope},
+		Endpoint: oauth2.Endpoint{
+			AuthURL:  base + "/open-apis/authen/v1/authorize",
+			TokenURL: base + "/open-apis/authen/v1/oidc/access_token",
+		},
+	}
+}
+
 // StartDeviceFlow generates a state token, constructs the authorization URL,
 // and stores a pending FlowStatus. The user must navigate to VerificationURI.
 func (b *LarkBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowStatus, error) {
 	flowID := uuid.NewString()
-	expiresAt := time.Now().Add(10 * time.Minute) // Lark code flows typically timeout within minutes
+	expiresAt := time.Now().Add(10 * time.Minute)
 
-	authURL, err := b.buildAuthURL(flowID)
-	if err != nil {
-		return FlowStatus{}, fmt.Errorf("oauthcli/lark: build auth url: %w", err)
-	}
+	authURL := b.oauthConfig().AuthCodeURL(flowID)
 
 	status := FlowStatus{
 		Provider:        ProviderLark,
@@ -117,7 +128,6 @@ func (b *LarkBroker) Poll(ctx context.Context, flowID string) (FlowStatus, error
 		return status, nil
 	}
 
-	// Check if Complete was called and stashed a bundle.
 	b.mu.Lock()
 	sec, ok := b.secret[flowID]
 	b.mu.Unlock()
@@ -156,7 +166,6 @@ func (b *LarkBroker) Complete(ctx context.Context, vs VaultStore, userID int64,
 		return err
 	}
 
-	// Update store so polling callers see the completion immediately.
 	b.store.Update(flowID, FlowStateAuthorized, nil)
 	b.mu.Lock()
 	if sec, ok := b.secret[flowID]; ok {
@@ -178,6 +187,8 @@ type larkAppTokenResponse struct {
 }
 
 // fetchAppAccessToken obtains a short-lived Lark app access token.
+// Lark requires a separate app credential exchange before user token operations —
+// the standard oauth2 flow does not support this pattern.
 func (b *LarkBroker) fetchAppAccessToken(ctx context.Context) (string, error) {
 	endpoint := b.baseURL() + "/open-apis/auth/v3/app_access_token/internal"
 	reqBody := map[string]string{
@@ -208,6 +219,8 @@ type larkUserTokenResponse struct {
 }
 
 // exchangeCode exchanges an authorization code for a user access token.
+// Uses custom HTTP because Lark requires Authorization: Bearer <app_access_token>,
+// which the standard oauth2.Config.Exchange() does not support.
 func (b *LarkBroker) exchangeCode(ctx context.Context, appToken string, code string) (*LarkOAuthBundle, error) {
 	endpoint := b.baseURL() + "/open-apis/authen/v1/oidc/access_token"
 	reqBody := map[string]string{
@@ -235,21 +248,6 @@ func (b *LarkBroker) exchangeCode(ctx context.Context, appToken string, code str
 	return bundle, nil
 }
 
-func (b *LarkBroker) buildAuthURL(state string) (string, error) {
-	base := b.baseURL() + "/open-apis/authen/v1/authorize"
-	params := url.Values{}
-	params.Set("app_id", b.cfg.AppID)
-	params.Set("redirect_uri", b.redirectURI)
-	params.Set("state", state)
-	params.Set("scope", "contact:user.base:readonly")
-	u, err := url.Parse(base)
-	if err != nil {
-		return "", err
-	}
-	u.RawQuery = params.Encode()
-	return u.String(), nil
-}
-
 func (b *LarkBroker) cleanSecret(flowID string) {
 	b.mu.Lock()
 	delete(b.secret, flowID)

From 69f88aa1222e93db356bd506834ccf837b283a2c Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 08:59:48 +0800
Subject: [PATCH 09/21] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor(oauthcli):?=
 =?UTF-8?q?=20simplify=20vault=20generics,=20remove=20dead=20lark=20secret?=
 =?UTF-8?q?=20map,=20drop=20unused=20params?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- vault.go: replace duplicate marshal/unmarshal logic with generic saveBundle/loadBundle helpers
- lark.go: remove larkFlowSecret struct and secret map (bundle field was unreachable in Poll)
- token_manager.go: drop unused appID/brand params from GetLarkRuntimeEnv
- sandbox_backend.go: update call site to match new signature

Assisted-by: Claude Code:claude-sonnet-4-6
---
 internal/agent/runner/sandbox_backend.go |  2 +-
 internal/oauthcli/lark.go                | 72 +++---------------------
 internal/oauthcli/token_manager.go       | 11 ++--
 internal/oauthcli/vault.go               | 55 ++++++++----------
 4 files changed, 35 insertions(+), 105 deletions(-)

diff --git a/internal/agent/runner/sandbox_backend.go b/internal/agent/runner/sandbox_backend.go
index fe1f965c..3fa5d8f2 100644
--- a/internal/agent/runner/sandbox_backend.go
+++ b/internal/agent/runner/sandbox_backend.go
@@ -160,7 +160,7 @@ func buildSandboxEnv(ctx context.Context, cfg GoRunnerConfig, paths sandboxPaths
 			)
 		}
 
-		if larkEnv, err := cfg.TokenManager.GetLarkRuntimeEnv(ctx, cfg.UserID, cfg.LarkAppID, cfg.LarkBrand); err == nil {
+		if larkEnv, err := cfg.TokenManager.GetLarkRuntimeEnv(ctx, cfg.UserID); err == nil {
 			maps.Copy(env, larkEnv)
 		} else {
 			slog.Debug("lark env injection skipped",
diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
index da573c57..77eab5e1 100644
--- a/internal/oauthcli/lark.go
+++ b/internal/oauthcli/lark.go
@@ -3,7 +3,6 @@ package oauthcli
 import (
 	"context"
 	"fmt"
-	"sync"
 	"time"
 
 	"github.com/google/uuid"
@@ -25,11 +24,6 @@ type LarkConfig struct {
 	Brand     string // "lark" or "feishu"
 }
 
-// larkFlowSecret holds provider-specific state for an in-flight Lark flow.
-type larkFlowSecret struct {
-	bundle *LarkOAuthBundle
-}
-
 // LarkBroker manages Lark/Feishu OAuth sessions via the authorization-code
 // flow adapted for device-like use: StartDeviceFlow returns a URL the user
 // visits; Poll checks completion; Complete exchanges the code and saves the
@@ -38,31 +32,18 @@ type LarkBroker struct {
 	cfg         LarkConfig
 	store       *FlowStore
 	redirectURI string
-	mu          sync.Mutex
-	secret      map[string]*larkFlowSecret
 }
 
 // NewLarkBroker constructs a LarkBroker. redirectURI is the OAuth callback URL
 // that your HTTP handler will receive and then call Complete on.
 func NewLarkBroker(cfg LarkConfig, store *FlowStore) *LarkBroker {
-	return &LarkBroker{
-		cfg:         cfg,
-		store:       store,
-		redirectURI: larkRedirectURI,
-		secret:      make(map[string]*larkFlowSecret),
-	}
+	return &LarkBroker{cfg: cfg, store: store, redirectURI: larkRedirectURI}
 }
 
 // WithRedirectURI returns a new broker with the same configuration but the
-// given redirect URI. The new broker has its own independent mutex and secret
-// map, so it is safe to use concurrently with the original.
+// given redirect URI.
 func (b *LarkBroker) WithRedirectURI(uri string) *LarkBroker {
-	return &LarkBroker{
-		cfg:         b.cfg,
-		store:       b.store,
-		redirectURI: uri,
-		secret:      make(map[string]*larkFlowSecret),
-	}
+	return &LarkBroker{cfg: b.cfg, store: b.store, redirectURI: uri}
 }
 
 func (b *LarkBroker) baseURL() string {
@@ -89,23 +70,14 @@ func (b *LarkBroker) oauthConfig() *oauth2.Config {
 // and stores a pending FlowStatus. The user must navigate to VerificationURI.
 func (b *LarkBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowStatus, error) {
 	flowID := uuid.NewString()
-	expiresAt := time.Now().Add(10 * time.Minute)
-
-	authURL := b.oauthConfig().AuthCodeURL(flowID)
-
 	status := FlowStatus{
 		Provider:        ProviderLark,
 		FlowID:          flowID,
-		VerificationURI: authURL,
-		ExpiresAt:       expiresAt,
+		VerificationURI: b.oauthConfig().AuthCodeURL(flowID),
+		ExpiresAt:       time.Now().Add(10 * time.Minute),
 		State:           FlowStatePending,
 	}
-
 	b.store.Create(status)
-	b.mu.Lock()
-	b.secret[flowID] = &larkFlowSecret{}
-	b.mu.Unlock()
-
 	return status, nil
 }
 
@@ -116,26 +88,13 @@ func (b *LarkBroker) Poll(ctx context.Context, flowID string) (FlowStatus, error
 	if !ok {
 		return FlowStatus{}, fmt.Errorf("oauthcli/lark: unknown flow %q", flowID)
 	}
-
 	if status.State != FlowStatePending {
 		return status, nil
 	}
-
 	if time.Now().After(status.ExpiresAt) {
 		b.store.Update(flowID, FlowStateExpired, nil)
-		b.cleanSecret(flowID)
 		status.State = FlowStateExpired
-		return status, nil
 	}
-
-	b.mu.Lock()
-	sec, ok := b.secret[flowID]
-	b.mu.Unlock()
-	if ok && sec.bundle != nil {
-		status.State = FlowStateAuthorized
-		return status, nil
-	}
-
 	return status, nil
 }
 
@@ -143,8 +102,7 @@ func (b *LarkBroker) Poll(ctx context.Context, flowID string) (FlowStatus, error
 // vault, and marks the flow as authorized. The code comes from your OAuth
 // callback handler's query parameter.
 func (b *LarkBroker) Complete(ctx context.Context, vs VaultStore, userID int64, flowID string, code string) error {
-	_, ok := b.store.Get(flowID)
-	if !ok {
+	if _, ok := b.store.Get(flowID); !ok {
 		return fmt.Errorf("oauthcli/lark: unknown flow %q", flowID)
 	}
 
@@ -167,14 +125,7 @@ func (b *LarkBroker) Complete(ctx context.Context, vs VaultStore, userID int64,
 	}
 
 	b.store.Update(flowID, FlowStateAuthorized, nil)
-	b.mu.Lock()
-	if sec, ok := b.secret[flowID]; ok {
-		sec.bundle = bundle
-	}
-	b.mu.Unlock()
-
 	b.store.Delete(flowID)
-	b.cleanSecret(flowID)
 	return nil
 }
 
@@ -239,17 +190,10 @@ func (b *LarkBroker) exchangeCode(ctx context.Context, appToken string, code str
 	}
 
 	now := time.Now()
-	bundle := &LarkOAuthBundle{
+	return &LarkOAuthBundle{
 		AccessToken:      resp.Data.AccessToken,
 		RefreshToken:     resp.Data.RefreshToken,
 		AccessExpiresAt:  now.Add(time.Duration(resp.Data.ExpiresIn) * time.Second),
 		RefreshExpiresAt: now.Add(time.Duration(resp.Data.RefreshExpiresIn) * time.Second),
-	}
-	return bundle, nil
-}
-
-func (b *LarkBroker) cleanSecret(flowID string) {
-	b.mu.Lock()
-	delete(b.secret, flowID)
-	b.mu.Unlock()
+	}, nil
 }
diff --git a/internal/oauthcli/token_manager.go b/internal/oauthcli/token_manager.go
index bf9a3c54..6c447959 100644
--- a/internal/oauthcli/token_manager.go
+++ b/internal/oauthcli/token_manager.go
@@ -39,13 +39,10 @@ func (m *TokenManager) GetGHToken(ctx context.Context, userID int64) (string, er
 }
 
 // GetLarkRuntimeEnv returns the environment variables needed for lark-cli.
-// It loads the Lark bundle, refreshes the access token if expired (using the
-// bundle's stored AppSecret), and returns a map ready for env injection.
-//
-// If the bundle is absent or fully expired (refresh token expired), it returns
-// a descriptive error so the runner can skip Lark env injection without failing
-// the entire session.
-func (m *TokenManager) GetLarkRuntimeEnv(ctx context.Context, userID int64, appID, brand string) (map[string]string, error) {
+// It loads the Lark bundle, refreshes the access token if expired, and returns
+// a map ready for env injection. Returns an error if the bundle is absent or
+// the refresh token has expired, so callers can skip injection without failing.
+func (m *TokenManager) GetLarkRuntimeEnv(ctx context.Context, userID int64) (map[string]string, error) {
 	bundle, err := LoadLarkBundle(ctx, m.vs, userID)
 	if err != nil {
 		return nil, fmt.Errorf("oauthcli: get lark env: %w", err)
diff --git a/internal/oauthcli/vault.go b/internal/oauthcli/vault.go
index 96dcf421..fb494403 100644
--- a/internal/oauthcli/vault.go
+++ b/internal/oauthcli/vault.go
@@ -13,64 +13,53 @@ type VaultStore interface {
 	LoadEnv(ctx context.Context, userID int64) (map[string]string, error)
 }
 
-// SaveGHBundle serializes bundle to JSON and stores it under VaultKeyGitHub.
-func SaveGHBundle(ctx context.Context, vs VaultStore, userID int64, bundle GHOAuthBundle) error {
+func saveBundle[T any](ctx context.Context, vs VaultStore, userID int64, key string, bundle T) error {
 	data, err := json.Marshal(bundle)
 	if err != nil {
-		return fmt.Errorf("oauthcli: marshal gh bundle: %w", err)
+		return fmt.Errorf("oauthcli: marshal bundle %q: %w", key, err)
 	}
-	if err := vs.Set(ctx, userID, VaultKeyGitHub, string(data)); err != nil {
-		return fmt.Errorf("oauthcli: save gh bundle: %w", err)
+	if err := vs.Set(ctx, userID, key, string(data)); err != nil {
+		return fmt.Errorf("oauthcli: save bundle %q: %w", key, err)
 	}
 	return nil
 }
 
-// LoadGHBundle retrieves and deserializes the GitHub token bundle for userID.
-// Returns nil, nil if no entry exists yet.
-func LoadGHBundle(ctx context.Context, vs VaultStore, userID int64) (*GHOAuthBundle, error) {
+func loadBundle[T any](ctx context.Context, vs VaultStore, userID int64, key string) (*T, error) {
 	env, err := vs.LoadEnv(ctx, userID)
 	if err != nil {
-		return nil, fmt.Errorf("oauthcli: load gh bundle: %w", err)
+		return nil, fmt.Errorf("oauthcli: load bundle %q: %w", key, err)
 	}
-	raw, ok := env[VaultKeyGitHub]
+	raw, ok := env[key]
 	if !ok {
 		return nil, nil
 	}
-	var bundle GHOAuthBundle
+	var bundle T
 	if err := json.Unmarshal([]byte(raw), &bundle); err != nil {
-		return nil, fmt.Errorf("oauthcli: unmarshal gh bundle: %w", err)
+		return nil, fmt.Errorf("oauthcli: unmarshal bundle %q: %w", key, err)
 	}
 	return &bundle, nil
 }
 
+// SaveGHBundle serializes bundle to JSON and stores it under VaultKeyGitHub.
+func SaveGHBundle(ctx context.Context, vs VaultStore, userID int64, bundle GHOAuthBundle) error {
+	return saveBundle(ctx, vs, userID, VaultKeyGitHub, bundle)
+}
+
+// LoadGHBundle retrieves and deserializes the GitHub token bundle for userID.
+// Returns nil, nil if no entry exists yet.
+func LoadGHBundle(ctx context.Context, vs VaultStore, userID int64) (*GHOAuthBundle, error) {
+	return loadBundle[GHOAuthBundle](ctx, vs, userID, VaultKeyGitHub)
+}
+
 // SaveLarkBundle serializes bundle to JSON and stores it under VaultKeyLark.
 func SaveLarkBundle(ctx context.Context, vs VaultStore, userID int64, bundle LarkOAuthBundle) error {
-	data, err := json.Marshal(bundle)
-	if err != nil {
-		return fmt.Errorf("oauthcli: marshal lark bundle: %w", err)
-	}
-	if err := vs.Set(ctx, userID, VaultKeyLark, string(data)); err != nil {
-		return fmt.Errorf("oauthcli: save lark bundle: %w", err)
-	}
-	return nil
+	return saveBundle(ctx, vs, userID, VaultKeyLark, bundle)
 }
 
 // LoadLarkBundle retrieves and deserializes the Lark token bundle for userID.
 // Returns nil, nil if no entry exists yet.
 func LoadLarkBundle(ctx context.Context, vs VaultStore, userID int64) (*LarkOAuthBundle, error) {
-	env, err := vs.LoadEnv(ctx, userID)
-	if err != nil {
-		return nil, fmt.Errorf("oauthcli: load lark bundle: %w", err)
-	}
-	raw, ok := env[VaultKeyLark]
-	if !ok {
-		return nil, nil
-	}
-	var bundle LarkOAuthBundle
-	if err := json.Unmarshal([]byte(raw), &bundle); err != nil {
-		return nil, fmt.Errorf("oauthcli: unmarshal lark bundle: %w", err)
-	}
-	return &bundle, nil
+	return loadBundle[LarkOAuthBundle](ctx, vs, userID, VaultKeyLark)
 }
 
 // DeleteBundle removes the vault entry identified by key for userID.

From bce0b4ca709c0520dba5baffbbcb59c05d9d0509 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 09:06:25 +0800
Subject: [PATCH 10/21] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor(oauthcli):?=
 =?UTF-8?q?=20use=20oauth2=20library=20for=20all=20Lark=20token=20flows?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace custom postJSON token exchange and refresh with golang.org/x/oauth2:
- Add larkTokenTransport: converts form-encoded→JSON requests, injects
  app_access_token as Bearer, and unwraps Lark's {"code":0,"data":{…}}
  envelope to flat OAuth2 JSON so the library can parse it normally.
- LarkBroker.Complete: uses cfg.Exchange() via larkOAuthContext.
- TokenManager.refreshLarkToken: uses cfg.TokenSource() pointed at Lark's
  dedicated refresh endpoint.
- Extract fetchLarkAppToken and larkBundleFromToken as shared helpers;
  remove larkUserTokenResponse and larkRefreshResponse hand-rolled types.
- larkBaseURL promoted to package-level (was LarkBroker method).

Assisted-by: Claude Code:claude-sonnet-4-6
---
 internal/oauthcli/lark.go          | 197 ++++++++++++++++++++---------
 internal/oauthcli/token_manager.go |  93 ++++++--------
 2 files changed, 174 insertions(+), 116 deletions(-)

diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
index 77eab5e1..a1864ff3 100644
--- a/internal/oauthcli/lark.go
+++ b/internal/oauthcli/lark.go
@@ -1,8 +1,13 @@
 package oauthcli
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"fmt"
+	"io"
+	"net/http"
+	"net/url"
 	"time"
 
 	"github.com/google/uuid"
@@ -46,26 +51,128 @@ func (b *LarkBroker) WithRedirectURI(uri string) *LarkBroker {
 	return &LarkBroker{cfg: b.cfg, store: b.store, redirectURI: uri}
 }
 
-func (b *LarkBroker) baseURL() string {
-	if b.cfg.Brand == "feishu" {
+func larkBaseURL(brand string) string {
+	if brand == "feishu" {
 		return larkBaseFeishu
 	}
 	return larkBaseLark
 }
 
 func (b *LarkBroker) oauthConfig() *oauth2.Config {
-	base := b.baseURL()
+	base := larkBaseURL(b.cfg.Brand)
 	return &oauth2.Config{
 		ClientID:    b.cfg.AppID,
 		RedirectURL: b.redirectURI,
 		Scopes:      []string{larkScope},
 		Endpoint: oauth2.Endpoint{
-			AuthURL:  base + "/open-apis/authen/v1/authorize",
-			TokenURL: base + "/open-apis/authen/v1/oidc/access_token",
+			AuthURL:   base + "/open-apis/authen/v1/authorize",
+			TokenURL:  base + "/open-apis/authen/v1/oidc/access_token",
+			AuthStyle: oauth2.AuthStyleInParams,
 		},
 	}
 }
 
+// larkTokenTransport adapts Lark's non-standard OIDC token endpoints for use
+// with golang.org/x/oauth2. It:
+//   - converts the library's form-encoded request body to JSON (Lark expects JSON),
+//   - injects the app access token as Authorization: Bearer,
+//   - unwraps Lark's {"code":0,"data":{…}} envelope to flat OAuth2 JSON so the
+//     library can parse the response normally.
+//
+// refresh_expires_in is preserved as an extra field so callers can read it via
+// tok.Extra("refresh_expires_in").
+type larkTokenTransport struct {
+	appToken string
+}
+
+func (t *larkTokenTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req = req.Clone(req.Context())
+	req.Header.Set("Authorization", "Bearer "+t.appToken)
+
+	// oauth2 sends form-encoded; Lark's OIDC endpoints expect JSON.
+	if req.Body != nil && req.Header.Get("Content-Type") == "application/x-www-form-urlencoded" {
+		raw, err := io.ReadAll(req.Body)
+		req.Body.Close()
+		if err != nil {
+			return nil, err
+		}
+		vals, _ := url.ParseQuery(string(raw))
+		m := make(map[string]string, len(vals))
+		for k, vs := range vals {
+			if len(vs) > 0 {
+				m[k] = vs[0]
+			}
+		}
+		jsonBody, _ := json.Marshal(m)
+		req.Body = io.NopCloser(bytes.NewReader(jsonBody))
+		req.ContentLength = int64(len(jsonBody))
+		req.Header.Set("Content-Type", "application/json; charset=utf-8")
+	}
+
+	resp, err := http.DefaultTransport.RoundTrip(req)
+	if err != nil {
+		return nil, err
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	resp.Body.Close()
+	if err != nil {
+		return nil, err
+	}
+
+	var larkResp struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+		Data struct {
+			AccessToken      string `json:"access_token"`
+			RefreshToken     string `json:"refresh_token"`
+			ExpiresIn        int    `json:"expires_in"`
+			RefreshExpiresIn int    `json:"refresh_expires_in"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &larkResp); err != nil {
+		// Not a Lark envelope — pass through as-is.
+		resp.Body = io.NopCloser(bytes.NewReader(body))
+		return resp, nil
+	}
+	if larkResp.Code != 0 {
+		errBody := fmt.Appendf(nil, `{"error":"lark_%d","error_description":%q}`, larkResp.Code, larkResp.Msg)
+		resp.StatusCode = http.StatusBadRequest
+		resp.Body = io.NopCloser(bytes.NewReader(errBody))
+		resp.ContentLength = int64(len(errBody))
+		return resp, nil
+	}
+
+	// Rewrite to flat OAuth2 JSON; include refresh_expires_in as an extra field
+	// so callers can read it via tok.Extra("refresh_expires_in").
+	flat := struct {
+		AccessToken      string `json:"access_token"`
+		RefreshToken     string `json:"refresh_token"`
+		ExpiresIn        int    `json:"expires_in"`
+		TokenType        string `json:"token_type"`
+		RefreshExpiresIn int    `json:"refresh_expires_in"`
+	}{
+		AccessToken:      larkResp.Data.AccessToken,
+		RefreshToken:     larkResp.Data.RefreshToken,
+		ExpiresIn:        larkResp.Data.ExpiresIn,
+		TokenType:        "Bearer",
+		RefreshExpiresIn: larkResp.Data.RefreshExpiresIn,
+	}
+	flatBody, _ := json.Marshal(flat)
+	resp.StatusCode = http.StatusOK
+	resp.Body = io.NopCloser(bytes.NewReader(flatBody))
+	resp.ContentLength = int64(len(flatBody))
+	return resp, nil
+}
+
+// larkOAuthContext returns ctx with an HTTP client that routes Lark token
+// requests through larkTokenTransport.
+func larkOAuthContext(ctx context.Context, appToken string) context.Context {
+	return context.WithValue(ctx, oauth2.HTTPClient, &http.Client{
+		Transport: &larkTokenTransport{appToken: appToken},
+	})
+}
+
 // StartDeviceFlow generates a state token, constructs the authorization URL,
 // and stores a pending FlowStatus. The user must navigate to VerificationURI.
 func (b *LarkBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowStatus, error) {
@@ -106,21 +213,18 @@ func (b *LarkBroker) Complete(ctx context.Context, vs VaultStore, userID int64,
 		return fmt.Errorf("oauthcli/lark: unknown flow %q", flowID)
 	}
 
-	appToken, err := b.fetchAppAccessToken(ctx)
+	appToken, err := fetchLarkAppToken(ctx, larkBaseURL(b.cfg.Brand), b.cfg.AppID, b.cfg.AppSecret)
 	if err != nil {
 		return fmt.Errorf("oauthcli/lark: fetch app access token: %w", err)
 	}
 
-	bundle, err := b.exchangeCode(ctx, appToken, code)
+	tok, err := b.oauthConfig().Exchange(larkOAuthContext(ctx, appToken), code)
 	if err != nil {
 		return fmt.Errorf("oauthcli/lark: exchange code: %w", err)
 	}
-	bundle.AppID = b.cfg.AppID
-	bundle.AppSecret = b.cfg.AppSecret
-	bundle.Brand = b.cfg.Brand
-	bundle.Version = 1
 
-	if err := SaveLarkBundle(ctx, vs, userID, *bundle); err != nil {
+	bundle := larkBundleFromToken(tok, b.cfg.AppID, b.cfg.AppSecret, b.cfg.Brand)
+	if err := SaveLarkBundle(ctx, vs, userID, bundle); err != nil {
 		return err
 	}
 
@@ -137,17 +241,13 @@ type larkAppTokenResponse struct {
 	Expire         int    `json:"expire"`
 }
 
-// fetchAppAccessToken obtains a short-lived Lark app access token.
-// Lark requires a separate app credential exchange before user token operations —
-// the standard oauth2 flow does not support this pattern.
-func (b *LarkBroker) fetchAppAccessToken(ctx context.Context) (string, error) {
-	endpoint := b.baseURL() + "/open-apis/auth/v3/app_access_token/internal"
-	reqBody := map[string]string{
-		"app_id":     b.cfg.AppID,
-		"app_secret": b.cfg.AppSecret,
-	}
+// fetchLarkAppToken obtains a short-lived Lark app access token.
+// Lark requires a separate server-to-server credential exchange before any
+// user token operation — this step has no equivalent in standard OAuth2.
+func fetchLarkAppToken(ctx context.Context, base, appID, appSecret string) (string, error) {
+	endpoint := base + "/open-apis/auth/v3/app_access_token/internal"
 	var resp larkAppTokenResponse
-	if err := postJSON(ctx, endpoint, reqBody, nil, &resp); err != nil {
+	if err := postJSON(ctx, endpoint, map[string]string{"app_id": appID, "app_secret": appSecret}, nil, &resp); err != nil {
 		return "", fmt.Errorf("app_access_token request: %w", err)
 	}
 	if resp.Code != 0 {
@@ -156,44 +256,21 @@ func (b *LarkBroker) fetchAppAccessToken(ctx context.Context) (string, error) {
 	return resp.AppAccessToken, nil
 }
 
-// larkUserTokenResponse is the JSON body from the OIDC access_token endpoint.
-type larkUserTokenResponse struct {
-	Code int    `json:"code"`
-	Msg  string `json:"msg"`
-	Data struct {
-		AccessToken      string `json:"access_token"`
-		RefreshToken     string `json:"refresh_token"`
-		ExpiresIn        int    `json:"expires_in"`
-		RefreshExpiresIn int    `json:"refresh_expires_in"`
-		TokenType        string `json:"token_type"`
-	} `json:"data"`
-}
-
-// exchangeCode exchanges an authorization code for a user access token.
-// Uses custom HTTP because Lark requires Authorization: Bearer <app_access_token>,
-// which the standard oauth2.Config.Exchange() does not support.
-func (b *LarkBroker) exchangeCode(ctx context.Context, appToken string, code string) (*LarkOAuthBundle, error) {
-	endpoint := b.baseURL() + "/open-apis/authen/v1/oidc/access_token"
-	reqBody := map[string]string{
-		"grant_type": "authorization_code",
-		"code":       code,
+// larkBundleFromToken builds a LarkOAuthBundle from an oauth2.Token returned
+// by Exchange or TokenSource. The non-standard refresh_expires_in field is
+// read from the token's extra claims.
+func larkBundleFromToken(tok *oauth2.Token, appID, appSecret, brand string) LarkOAuthBundle {
+	bundle := LarkOAuthBundle{
+		Version:         1,
+		AppID:           appID,
+		AppSecret:       appSecret,
+		Brand:           brand,
+		AccessToken:     tok.AccessToken,
+		RefreshToken:    tok.RefreshToken,
+		AccessExpiresAt: tok.Expiry,
 	}
-	headers := map[string]string{
-		"Authorization": "Bearer " + appToken,
+	if ri, ok := tok.Extra("refresh_expires_in").(float64); ok && ri > 0 {
+		bundle.RefreshExpiresAt = time.Now().Add(time.Duration(ri) * time.Second)
 	}
-	var resp larkUserTokenResponse
-	if err := postJSON(ctx, endpoint, reqBody, headers, &resp); err != nil {
-		return nil, fmt.Errorf("token exchange request: %w", err)
-	}
-	if resp.Code != 0 {
-		return nil, fmt.Errorf("token exchange error %d: %s", resp.Code, resp.Msg)
-	}
-
-	now := time.Now()
-	return &LarkOAuthBundle{
-		AccessToken:      resp.Data.AccessToken,
-		RefreshToken:     resp.Data.RefreshToken,
-		AccessExpiresAt:  now.Add(time.Duration(resp.Data.ExpiresIn) * time.Second),
-		RefreshExpiresAt: now.Add(time.Duration(resp.Data.RefreshExpiresIn) * time.Second),
-	}, nil
+	return bundle
 }
diff --git a/internal/oauthcli/token_manager.go b/internal/oauthcli/token_manager.go
index 6c447959..d0640931 100644
--- a/internal/oauthcli/token_manager.go
+++ b/internal/oauthcli/token_manager.go
@@ -3,7 +3,10 @@ package oauthcli
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"time"
+
+	"golang.org/x/oauth2"
 )
 
 // tokenExpirySafetyMargin is subtracted from expiry times to avoid using
@@ -73,74 +76,52 @@ func (m *TokenManager) GetLarkRuntimeEnv(ctx context.Context, userID int64) (map
 		bundle = refreshed
 	}
 
-	env := map[string]string{
+	return map[string]string{
 		"LARK_ACCESS_TOKEN": bundle.AccessToken,
 		"LARK_APP_ID":       bundle.AppID,
 		"LARK_BRAND":        bundle.Brand,
-	}
-	return env, nil
-}
-
-// larkRefreshResponse is the JSON body from the OIDC refresh_access_token endpoint.
-type larkRefreshResponse struct {
-	Code int    `json:"code"`
-	Msg  string `json:"msg"`
-	Data struct {
-		AccessToken      string `json:"access_token"`
-		RefreshToken     string `json:"refresh_token"`
-		ExpiresIn        int    `json:"expires_in"`
-		RefreshExpiresIn int    `json:"refresh_expires_in"`
-	} `json:"data"`
+	}, nil
 }
 
-// refreshLarkToken exchanges the bundle's refresh token for a new access
-// token, returning an updated bundle. The original bundle is not mutated.
+// refreshLarkToken fetches a new app access token, then uses the oauth2
+// library's TokenSource to refresh the user access token via Lark's OIDC
+// refresh endpoint. larkTokenTransport adapts Lark's non-standard request
+// and response format for the library.
 func (m *TokenManager) refreshLarkToken(ctx context.Context, bundle *LarkOAuthBundle) (*LarkOAuthBundle, error) {
-	base := larkBaseFeishu
-	if bundle.Brand == "lark" {
-		base = larkBaseLark
-	}
+	base := larkBaseURL(bundle.Brand)
 
-	// Obtain a fresh app access token using the stored credentials.
-	appTokenEndpoint := base + "/open-apis/auth/v3/app_access_token/internal"
-	appTokenBody := map[string]string{
-		"app_id":     bundle.AppID,
-		"app_secret": bundle.AppSecret,
-	}
-	var appTokenResp larkAppTokenResponse
-	if err := postJSON(ctx, appTokenEndpoint, appTokenBody, nil, &appTokenResp); err != nil {
+	appToken, err := fetchLarkAppToken(ctx, base, bundle.AppID, bundle.AppSecret)
+	if err != nil {
 		return nil, fmt.Errorf("fetch app access token: %w", err)
 	}
-	if appTokenResp.Code != 0 {
-		return nil, fmt.Errorf("app_access_token error %d: %s", appTokenResp.Code, appTokenResp.Msg)
-	}
 
-	// Refresh the user access token.
-	refreshEndpoint := base + "/open-apis/authen/v1/oidc/refresh_access_token"
-	refreshBody := map[string]string{
-		"grant_type":    "refresh_token",
-		"refresh_token": bundle.RefreshToken,
-	}
-	headers := map[string]string{
-		"Authorization": "Bearer " + appTokenResp.AppAccessToken,
-	}
-	var refreshResp larkRefreshResponse
-	if err := postJSON(ctx, refreshEndpoint, refreshBody, headers, &refreshResp); err != nil {
-		return nil, fmt.Errorf("refresh token request: %w", err)
-	}
-	if refreshResp.Code != 0 {
-		return nil, fmt.Errorf("refresh token error %d: %s", refreshResp.Code, refreshResp.Msg)
+	cfg := &oauth2.Config{
+		ClientID: bundle.AppID,
+		Endpoint: oauth2.Endpoint{
+			// Lark uses a distinct endpoint for token refresh.
+			TokenURL:  base + "/open-apis/authen/v1/oidc/refresh_access_token",
+			AuthStyle: oauth2.AuthStyleInParams,
+		},
+	}
+	existing := &oauth2.Token{
+		AccessToken:  bundle.AccessToken,
+		RefreshToken: bundle.RefreshToken,
+		Expiry:       bundle.AccessExpiresAt, // expired → triggers refresh
+	}
+	refreshCtx := context.WithValue(ctx, oauth2.HTTPClient, &http.Client{
+		Transport: &larkTokenTransport{appToken: appToken},
+	})
+	tok, err := cfg.TokenSource(refreshCtx, existing).Token()
+	if err != nil {
+		return nil, fmt.Errorf("refresh token: %w", err)
 	}
 
-	now := time.Now()
-	refreshed := *bundle // shallow copy; all fields are value types or immutable strings
-	refreshed.AccessToken = refreshResp.Data.AccessToken
-	if refreshResp.Data.RefreshToken != "" {
-		refreshed.RefreshToken = refreshResp.Data.RefreshToken
-	}
-	refreshed.AccessExpiresAt = now.Add(time.Duration(refreshResp.Data.ExpiresIn) * time.Second)
-	if refreshResp.Data.RefreshExpiresIn > 0 {
-		refreshed.RefreshExpiresAt = now.Add(time.Duration(refreshResp.Data.RefreshExpiresIn) * time.Second)
+	refreshed := larkBundleFromToken(tok, bundle.AppID, bundle.AppSecret, bundle.Brand)
+	// larkBundleFromToken sets Version to 1; preserve the existing version.
+	refreshed.Version = bundle.Version
+	// Only update RefreshExpiresAt if the server returned a new value.
+	if refreshed.RefreshExpiresAt.IsZero() {
+		refreshed.RefreshExpiresAt = bundle.RefreshExpiresAt
 	}
 	return &refreshed, nil
 }

From 324799dacbe83494c17497ca5da9cffe1b02ccdb Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 09:13:59 +0800
Subject: [PATCH 11/21] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor(oauthcli):?=
 =?UTF-8?q?=20switch=20Lark=20to=20v2=20OAuth=20endpoint,=20remove=20custo?=
 =?UTF-8?q?m=20transport?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lark's v2 token endpoint (/open-apis/authen/v2/oauth/token) follows standard
OAuth2: form-encoded requests with client_id/client_secret in body, flat JSON
responses. No app access token pre-fetch is required.

- Remove larkTokenTransport, larkOAuthContext, fetchLarkAppToken,
  larkAppTokenResponse — all workarounds for the old v1 OIDC endpoints.
- Delete http.go (postJSON helper, now unused).
- oauthConfig: add ClientSecret, point TokenURL at v2 endpoint.
- Complete: plain cfg.Exchange(ctx, code) — no custom HTTP client.
- refreshLarkToken: plain cfg.TokenSource(ctx, existing).Token() — no app
  token step, no custom transport.
- Update extra field key refresh_expires_in → refresh_token_expires_in (v2
  response field name).

Assisted-by: Claude Code:claude-sonnet-4-6
---
 internal/oauthcli/http.go          |  34 -------
 internal/oauthcli/lark.go          | 157 +++--------------------------
 internal/oauthcli/token_manager.go |  29 ++----
 3 files changed, 22 insertions(+), 198 deletions(-)
 delete mode 100644 internal/oauthcli/http.go

diff --git a/internal/oauthcli/http.go b/internal/oauthcli/http.go
deleted file mode 100644
index 3e653608..00000000
--- a/internal/oauthcli/http.go
+++ /dev/null
@@ -1,34 +0,0 @@
-package oauthcli
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"net/http"
-)
-
-// postJSON POSTs a JSON body and decodes the JSON response into out.
-func postJSON(ctx context.Context, url string, reqBody any, headers map[string]string, out any) error {
-	data, err := json.Marshal(reqBody)
-	if err != nil {
-		return fmt.Errorf("marshal request: %w", err)
-	}
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(data))
-	if err != nil {
-		return fmt.Errorf("build request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json; charset=utf-8")
-	for k, v := range headers {
-		req.Header.Set(k, v)
-	}
-	resp, err := http.DefaultClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("do request: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return fmt.Errorf("unexpected status %d", resp.StatusCode)
-	}
-	return json.NewDecoder(resp.Body).Decode(out)
-}
diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
index a1864ff3..df739d46 100644
--- a/internal/oauthcli/lark.go
+++ b/internal/oauthcli/lark.go
@@ -1,13 +1,8 @@
 package oauthcli
 
 import (
-	"bytes"
 	"context"
-	"encoding/json"
 	"fmt"
-	"io"
-	"net/http"
-	"net/url"
 	"time"
 
 	"github.com/google/uuid"
@@ -58,121 +53,24 @@ func larkBaseURL(brand string) string {
 	return larkBaseLark
 }
 
+// oauthConfig returns an oauth2.Config for Lark's v2 token endpoint, which
+// follows standard OAuth2: form-encoded requests with client credentials in
+// the body, flat JSON responses. No app access token pre-fetch is required.
 func (b *LarkBroker) oauthConfig() *oauth2.Config {
 	base := larkBaseURL(b.cfg.Brand)
 	return &oauth2.Config{
-		ClientID:    b.cfg.AppID,
-		RedirectURL: b.redirectURI,
-		Scopes:      []string{larkScope},
+		ClientID:     b.cfg.AppID,
+		ClientSecret: b.cfg.AppSecret,
+		RedirectURL:  b.redirectURI,
+		Scopes:       []string{larkScope},
 		Endpoint: oauth2.Endpoint{
 			AuthURL:   base + "/open-apis/authen/v1/authorize",
-			TokenURL:  base + "/open-apis/authen/v1/oidc/access_token",
+			TokenURL:  base + "/open-apis/authen/v2/oauth/token",
 			AuthStyle: oauth2.AuthStyleInParams,
 		},
 	}
 }
 
-// larkTokenTransport adapts Lark's non-standard OIDC token endpoints for use
-// with golang.org/x/oauth2. It:
-//   - converts the library's form-encoded request body to JSON (Lark expects JSON),
-//   - injects the app access token as Authorization: Bearer,
-//   - unwraps Lark's {"code":0,"data":{…}} envelope to flat OAuth2 JSON so the
-//     library can parse the response normally.
-//
-// refresh_expires_in is preserved as an extra field so callers can read it via
-// tok.Extra("refresh_expires_in").
-type larkTokenTransport struct {
-	appToken string
-}
-
-func (t *larkTokenTransport) RoundTrip(req *http.Request) (*http.Response, error) {
-	req = req.Clone(req.Context())
-	req.Header.Set("Authorization", "Bearer "+t.appToken)
-
-	// oauth2 sends form-encoded; Lark's OIDC endpoints expect JSON.
-	if req.Body != nil && req.Header.Get("Content-Type") == "application/x-www-form-urlencoded" {
-		raw, err := io.ReadAll(req.Body)
-		req.Body.Close()
-		if err != nil {
-			return nil, err
-		}
-		vals, _ := url.ParseQuery(string(raw))
-		m := make(map[string]string, len(vals))
-		for k, vs := range vals {
-			if len(vs) > 0 {
-				m[k] = vs[0]
-			}
-		}
-		jsonBody, _ := json.Marshal(m)
-		req.Body = io.NopCloser(bytes.NewReader(jsonBody))
-		req.ContentLength = int64(len(jsonBody))
-		req.Header.Set("Content-Type", "application/json; charset=utf-8")
-	}
-
-	resp, err := http.DefaultTransport.RoundTrip(req)
-	if err != nil {
-		return nil, err
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	resp.Body.Close()
-	if err != nil {
-		return nil, err
-	}
-
-	var larkResp struct {
-		Code int    `json:"code"`
-		Msg  string `json:"msg"`
-		Data struct {
-			AccessToken      string `json:"access_token"`
-			RefreshToken     string `json:"refresh_token"`
-			ExpiresIn        int    `json:"expires_in"`
-			RefreshExpiresIn int    `json:"refresh_expires_in"`
-		} `json:"data"`
-	}
-	if err := json.Unmarshal(body, &larkResp); err != nil {
-		// Not a Lark envelope — pass through as-is.
-		resp.Body = io.NopCloser(bytes.NewReader(body))
-		return resp, nil
-	}
-	if larkResp.Code != 0 {
-		errBody := fmt.Appendf(nil, `{"error":"lark_%d","error_description":%q}`, larkResp.Code, larkResp.Msg)
-		resp.StatusCode = http.StatusBadRequest
-		resp.Body = io.NopCloser(bytes.NewReader(errBody))
-		resp.ContentLength = int64(len(errBody))
-		return resp, nil
-	}
-
-	// Rewrite to flat OAuth2 JSON; include refresh_expires_in as an extra field
-	// so callers can read it via tok.Extra("refresh_expires_in").
-	flat := struct {
-		AccessToken      string `json:"access_token"`
-		RefreshToken     string `json:"refresh_token"`
-		ExpiresIn        int    `json:"expires_in"`
-		TokenType        string `json:"token_type"`
-		RefreshExpiresIn int    `json:"refresh_expires_in"`
-	}{
-		AccessToken:      larkResp.Data.AccessToken,
-		RefreshToken:     larkResp.Data.RefreshToken,
-		ExpiresIn:        larkResp.Data.ExpiresIn,
-		TokenType:        "Bearer",
-		RefreshExpiresIn: larkResp.Data.RefreshExpiresIn,
-	}
-	flatBody, _ := json.Marshal(flat)
-	resp.StatusCode = http.StatusOK
-	resp.Body = io.NopCloser(bytes.NewReader(flatBody))
-	resp.ContentLength = int64(len(flatBody))
-	return resp, nil
-}
-
-// larkOAuthContext returns ctx with an HTTP client that routes Lark token
-// requests through larkTokenTransport.
-func larkOAuthContext(ctx context.Context, appToken string) context.Context {
-	return context.WithValue(ctx, oauth2.HTTPClient, &http.Client{
-		Transport: &larkTokenTransport{appToken: appToken},
-	})
-}
-
 // StartDeviceFlow generates a state token, constructs the authorization URL,
 // and stores a pending FlowStatus. The user must navigate to VerificationURI.
 func (b *LarkBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowStatus, error) {
@@ -213,17 +111,13 @@ func (b *LarkBroker) Complete(ctx context.Context, vs VaultStore, userID int64,
 		return fmt.Errorf("oauthcli/lark: unknown flow %q", flowID)
 	}
 
-	appToken, err := fetchLarkAppToken(ctx, larkBaseURL(b.cfg.Brand), b.cfg.AppID, b.cfg.AppSecret)
-	if err != nil {
-		return fmt.Errorf("oauthcli/lark: fetch app access token: %w", err)
-	}
-
-	tok, err := b.oauthConfig().Exchange(larkOAuthContext(ctx, appToken), code)
+	tok, err := b.oauthConfig().Exchange(ctx, code)
 	if err != nil {
 		return fmt.Errorf("oauthcli/lark: exchange code: %w", err)
 	}
 
 	bundle := larkBundleFromToken(tok, b.cfg.AppID, b.cfg.AppSecret, b.cfg.Brand)
+	bundle.Version = 1
 	if err := SaveLarkBundle(ctx, vs, userID, bundle); err != nil {
 		return err
 	}
@@ -233,35 +127,12 @@ func (b *LarkBroker) Complete(ctx context.Context, vs VaultStore, userID int64,
 	return nil
 }
 
-// larkAppTokenResponse is the JSON body from the app_access_token endpoint.
-type larkAppTokenResponse struct {
-	Code           int    `json:"code"`
-	Msg            string `json:"msg"`
-	AppAccessToken string `json:"app_access_token"`
-	Expire         int    `json:"expire"`
-}
-
-// fetchLarkAppToken obtains a short-lived Lark app access token.
-// Lark requires a separate server-to-server credential exchange before any
-// user token operation — this step has no equivalent in standard OAuth2.
-func fetchLarkAppToken(ctx context.Context, base, appID, appSecret string) (string, error) {
-	endpoint := base + "/open-apis/auth/v3/app_access_token/internal"
-	var resp larkAppTokenResponse
-	if err := postJSON(ctx, endpoint, map[string]string{"app_id": appID, "app_secret": appSecret}, nil, &resp); err != nil {
-		return "", fmt.Errorf("app_access_token request: %w", err)
-	}
-	if resp.Code != 0 {
-		return "", fmt.Errorf("app_access_token error %d: %s", resp.Code, resp.Msg)
-	}
-	return resp.AppAccessToken, nil
-}
-
 // larkBundleFromToken builds a LarkOAuthBundle from an oauth2.Token returned
-// by Exchange or TokenSource. The non-standard refresh_expires_in field is
-// read from the token's extra claims.
+// by Exchange or TokenSource. Version is left at zero; callers must set it.
+// refresh_token_expires_in is a non-standard Lark field preserved as a token
+// extra so callers can read it via tok.Extra("refresh_token_expires_in").
 func larkBundleFromToken(tok *oauth2.Token, appID, appSecret, brand string) LarkOAuthBundle {
 	bundle := LarkOAuthBundle{
-		Version:         1,
 		AppID:           appID,
 		AppSecret:       appSecret,
 		Brand:           brand,
@@ -269,7 +140,7 @@ func larkBundleFromToken(tok *oauth2.Token, appID, appSecret, brand string) Lark
 		RefreshToken:    tok.RefreshToken,
 		AccessExpiresAt: tok.Expiry,
 	}
-	if ri, ok := tok.Extra("refresh_expires_in").(float64); ok && ri > 0 {
+	if ri, ok := tok.Extra("refresh_token_expires_in").(float64); ok && ri > 0 {
 		bundle.RefreshExpiresAt = time.Now().Add(time.Duration(ri) * time.Second)
 	}
 	return bundle
diff --git a/internal/oauthcli/token_manager.go b/internal/oauthcli/token_manager.go
index d0640931..96c53616 100644
--- a/internal/oauthcli/token_manager.go
+++ b/internal/oauthcli/token_manager.go
@@ -3,12 +3,12 @@ package oauthcli
 import (
 	"context"
 	"fmt"
-	"net/http"
 	"time"
 
 	"golang.org/x/oauth2"
 )
 
+
 // tokenExpirySafetyMargin is subtracted from expiry times to avoid using
 // tokens that are about to expire during a long-running operation.
 const tokenExpirySafetyMargin = 2 * time.Minute
@@ -83,23 +83,15 @@ func (m *TokenManager) GetLarkRuntimeEnv(ctx context.Context, userID int64) (map
 	}, nil
 }
 
-// refreshLarkToken fetches a new app access token, then uses the oauth2
-// library's TokenSource to refresh the user access token via Lark's OIDC
-// refresh endpoint. larkTokenTransport adapts Lark's non-standard request
-// and response format for the library.
+// refreshLarkToken uses the oauth2 library's TokenSource to refresh the user
+// access token against Lark's v2 token endpoint (standard OAuth2 form-encoded,
+// no app access token pre-fetch required).
 func (m *TokenManager) refreshLarkToken(ctx context.Context, bundle *LarkOAuthBundle) (*LarkOAuthBundle, error) {
-	base := larkBaseURL(bundle.Brand)
-
-	appToken, err := fetchLarkAppToken(ctx, base, bundle.AppID, bundle.AppSecret)
-	if err != nil {
-		return nil, fmt.Errorf("fetch app access token: %w", err)
-	}
-
 	cfg := &oauth2.Config{
-		ClientID: bundle.AppID,
+		ClientID:     bundle.AppID,
+		ClientSecret: bundle.AppSecret,
 		Endpoint: oauth2.Endpoint{
-			// Lark uses a distinct endpoint for token refresh.
-			TokenURL:  base + "/open-apis/authen/v1/oidc/refresh_access_token",
+			TokenURL:  larkBaseURL(bundle.Brand) + "/open-apis/authen/v2/oauth/token",
 			AuthStyle: oauth2.AuthStyleInParams,
 		},
 	}
@@ -108,18 +100,13 @@ func (m *TokenManager) refreshLarkToken(ctx context.Context, bundle *LarkOAuthBu
 		RefreshToken: bundle.RefreshToken,
 		Expiry:       bundle.AccessExpiresAt, // expired → triggers refresh
 	}
-	refreshCtx := context.WithValue(ctx, oauth2.HTTPClient, &http.Client{
-		Transport: &larkTokenTransport{appToken: appToken},
-	})
-	tok, err := cfg.TokenSource(refreshCtx, existing).Token()
+	tok, err := cfg.TokenSource(ctx, existing).Token()
 	if err != nil {
 		return nil, fmt.Errorf("refresh token: %w", err)
 	}
 
 	refreshed := larkBundleFromToken(tok, bundle.AppID, bundle.AppSecret, bundle.Brand)
-	// larkBundleFromToken sets Version to 1; preserve the existing version.
 	refreshed.Version = bundle.Version
-	// Only update RefreshExpiresAt if the server returned a new value.
 	if refreshed.RefreshExpiresAt.IsZero() {
 		refreshed.RefreshExpiresAt = bundle.RefreshExpiresAt
 	}

From 9f30a36ee7a0372438cd33198f3df4f98771138d Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 09:15:35 +0800
Subject: [PATCH 12/21] =?UTF-8?q?=E2=9C=A8=20feat(oauthcli):=20expand=20Gi?=
 =?UTF-8?q?tHub=20OAuth=20scopes=20for=20human-level=20CLI=20access?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add workflow (push Actions files), gist, and user scopes alongside the
existing repo and read:org. Matches the scope set used by the gh CLI.
Switch from a single comma-joined const to a proper []string var so
the oauth2 library sends each scope individually.

Assisted-by: Claude Code:claude-sonnet-4-6
---
 internal/oauthcli/gh.go | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/internal/oauthcli/gh.go b/internal/oauthcli/gh.go
index 417d3af3..3161ccc7 100644
--- a/internal/oauthcli/gh.go
+++ b/internal/oauthcli/gh.go
@@ -11,7 +11,9 @@ import (
 	"golang.org/x/oauth2/github"
 )
 
-const ghScope = "repo,read:org"
+// ghScopes mirrors the scopes requested by the gh CLI for human-level access:
+// repo (full repo r/w including push), workflow (Actions files), gist, user, read:org.
+var ghScopes = []string{"repo", "workflow", "gist", "user", "read:org"}
 
 // GitHubConfig holds the OAuth app credentials for device flow.
 type GitHubConfig struct {
@@ -48,7 +50,7 @@ func (b *GitHubBroker) oauthConfig() *oauth2.Config {
 	return &oauth2.Config{
 		ClientID:     b.cfg.ClientID,
 		ClientSecret: b.cfg.ClientSecret,
-		Scopes:       []string{ghScope},
+		Scopes:       ghScopes,
 		Endpoint:     github.Endpoint,
 	}
 }

From 40787ce42af010a17d6ade135127fc78fcc74d3b Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 09:18:22 +0800
Subject: [PATCH 13/21] =?UTF-8?q?=E2=9C=A8=20feat(oauthcli):=20add=20offli?=
 =?UTF-8?q?ne=5Faccess=20scope=20and=20fix=20Lark=20scope=20declaration?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

lark-cli always appends offline_access to ensure the server issues a
refresh token. Without it the v2 endpoint may skip the refresh token,
breaking token renewal entirely.

Also switch from a single const string to a proper []string var
(matching the GitHub change) so the oauth2 library sends each scope
individually.

Assisted-by: Claude Code:claude-sonnet-4-6
---
 internal/oauthcli/lark.go | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
index df739d46..45cc92cb 100644
--- a/internal/oauthcli/lark.go
+++ b/internal/oauthcli/lark.go
@@ -14,9 +14,13 @@ const (
 	larkBaseLark   = "https://open.larksuite.com"
 
 	larkRedirectURI = "https://anna.app/oauth/lark/callback" // placeholder; caller sets up the real redirect
-	larkScope       = "contact:user.base:readonly"
 )
 
+// larkScopes are the OAuth scopes requested at login.
+// offline_access is required for the server to issue a refresh token.
+// contact:user.base:readonly provides basic identity info for the session.
+var larkScopes = []string{"offline_access", "contact:user.base:readonly"}
+
 // LarkConfig holds the OAuth app credentials for Lark/Feishu device-style flow.
 type LarkConfig struct {
 	AppID     string
@@ -62,7 +66,7 @@ func (b *LarkBroker) oauthConfig() *oauth2.Config {
 		ClientID:     b.cfg.AppID,
 		ClientSecret: b.cfg.AppSecret,
 		RedirectURL:  b.redirectURI,
-		Scopes:       []string{larkScope},
+		Scopes:       larkScopes,
 		Endpoint: oauth2.Endpoint{
 			AuthURL:   base + "/open-apis/authen/v1/authorize",
 			TokenURL:  base + "/open-apis/authen/v2/oauth/token",

From 02f486b172413420a4daedb21f901b4a3d9f9119 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 09:23:41 +0800
Subject: [PATCH 14/21] =?UTF-8?q?=E2=9C=A8=20feat(oauthcli):=20expand=20La?=
 =?UTF-8?q?rk=20scopes=20for=20daily=20Feishu=20life=20management?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cover the common use cases: IM read/send, calendar, all document types
(docs, docx, wiki, sheets, slides), tasks, and file downloads.

Scope choices:
- im:message + im:chat:readonly  — user-level messaging (not bot)
- calendar:calendar:readonly     — read events/free-busy
- drive:file:download + drive:drive.metadata:readonly
- docs:document.content:read + comment + export  (legacy format)
- docx:document, wiki:wiki, sheets:spreadsheet  (combined read/write)
- slides:presentation:read + update
- task:task + task:comment read/write

Assisted-by: Claude Code:claude-sonnet-4-6
---
 internal/oauthcli/lark.go | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
index 45cc92cb..3375e924 100644
--- a/internal/oauthcli/lark.go
+++ b/internal/oauthcli/lark.go
@@ -16,10 +16,40 @@ const (
 	larkRedirectURI = "https://anna.app/oauth/lark/callback" // placeholder; caller sets up the real redirect
 )
 
-// larkScopes are the OAuth scopes requested at login.
-// offline_access is required for the server to issue a refresh token.
-// contact:user.base:readonly provides basic identity info for the session.
-var larkScopes = []string{"offline_access", "contact:user.base:readonly"}
+// larkScopes covers common Feishu/Lark daily-use scenarios: IM read/send,
+// calendar, all document types (docs, docx, wiki, sheets, slides), tasks,
+// and file access. offline_access is required for refresh tokens.
+var larkScopes = []string{
+	"offline_access",
+	// Identity
+	"contact:user.base:readonly",
+	// IM — read and send messages as user, read chats
+	"im:message",
+	"im:chat:readonly",
+	// Calendar — read events and free/busy
+	"calendar:calendar:readonly",
+	// Drive — download files and read metadata
+	"drive:file:download",
+	"drive:drive.metadata:readonly",
+	// Docs (legacy doc format) — read content, comments, export
+	"docs:document.content:read",
+	"docs:document.comment:read",
+	"docs:document.comment:create",
+	"docs:document:export",
+	// Docx (new document format) — full read/write
+	"docx:document",
+	// Wiki — full read/write
+	"wiki:wiki",
+	// Sheets — full read/write
+	"sheets:spreadsheet",
+	// Slides — read and update presentations
+	"slides:presentation:read",
+	"slides:presentation:update",
+	// Tasks — full read/write with comments
+	"task:task",
+	"task:comment:read",
+	"task:comment:write",
+}
 
 // LarkConfig holds the OAuth app credentials for Lark/Feishu device-style flow.
 type LarkConfig struct {

From d5c36faf28928f4057a551b0e3f68449f6a873a1 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 09:29:33 +0800
Subject: [PATCH 15/21] =?UTF-8?q?=F0=9F=90=9B=20fix(config):=20seed=20auth?=
 =?UTF-8?q?/github=20and=20auth/lark=20plugins=20on=20startup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both plugins were defined and imported but never inserted into
settings_plugins, causing "sql: no rows in result set" whenever
the admin OAuth routes called pluginHost.Config().Get().

- Add PluginKindAuth = "auth" constant
- Add builtinAuthNames = ["github", "lark"]
- Include auth plugins in BuiltinPluginIDs()
- Call seedBuiltinPlugins for auth kind in seedPlugins()

Auth plugins seed with enabled=0 (disabled by default, requiring
explicit configuration before activation).

Assisted-by: Claude Code:claude-sonnet-4-6
---
 internal/config/dbstore.go | 4 ++++
 internal/config/plugin.go  | 9 ++++++++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/internal/config/dbstore.go b/internal/config/dbstore.go
index 1a9624ad..901991de 100644
--- a/internal/config/dbstore.go
+++ b/internal/config/dbstore.go
@@ -633,6 +633,10 @@ func (s *DBStore) seedPlugins(ctx context.Context) error {
 		return err
 	}
 
+	if err := s.seedBuiltinPlugins(ctx, PluginKindAuth, builtinAuthNames, nil); err != nil {
+		return err
+	}
+
 	// Seed the reflect plugin (conversation review).
 	if err := s.q.SeedPlugin(ctx, sqlc.SeedPluginParams{
 		ID:      "reflect",
diff --git a/internal/config/plugin.go b/internal/config/plugin.go
index 1a82bee3..edc52326 100644
--- a/internal/config/plugin.go
+++ b/internal/config/plugin.go
@@ -8,6 +8,7 @@ const (
 	PluginKindProvider = "provider"
 	PluginKindMemory   = "memory"
 	PluginKindSandbox  = "sandbox"
+	PluginKindAuth     = "auth"
 )
 
 // Plugin represents a unified plugin entry stored in settings_plugins.
@@ -44,13 +45,16 @@ var builtinMemoryNames = []string{"lcm", "simple"}
 // has been removed; enabling them will fail at runtime with a clear error.
 var builtinSandboxNames = []string{SandboxBackendDocker, SandboxBackendBoxsh, SandboxBackendLocal}
 
+// builtinAuthNames lists the built-in OAuth provider plugins.
+var builtinAuthNames = []string{"github", "lark"}
+
 // builtinStandalonePlugins lists plugins that don't follow the kind/name pattern.
 var builtinStandalonePlugins = []string{"reflect"}
 
 // BuiltinPluginIDs returns all built-in plugin IDs in deterministic order.
 // Provider instances are stored separately in settings_providers.
 func BuiltinPluginIDs() []string {
-	ids := make([]string, 0, len(builtinToolNames)+len(builtinChannelNames)+len(builtinHookNames)+len(builtinMemoryNames)+len(builtinSandboxNames)+len(builtinStandalonePlugins))
+	ids := make([]string, 0, len(builtinToolNames)+len(builtinChannelNames)+len(builtinHookNames)+len(builtinMemoryNames)+len(builtinSandboxNames)+len(builtinAuthNames)+len(builtinStandalonePlugins))
 	for _, n := range builtinToolNames {
 		ids = append(ids, PluginID(PluginKindTool, n))
 	}
@@ -66,6 +70,9 @@ func BuiltinPluginIDs() []string {
 	for _, n := range builtinSandboxNames {
 		ids = append(ids, PluginID(PluginKindSandbox, n))
 	}
+	for _, n := range builtinAuthNames {
+		ids = append(ids, PluginID(PluginKindAuth, n))
+	}
 	ids = append(ids, builtinStandalonePlugins...)
 	return ids
 }

From cc5733b015c051d260863cb1d47cddad8a87756c Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 10:10:14 +0800
Subject: [PATCH 16/21] =?UTF-8?q?=E2=9C=A8=20feat(oauthcli):=20add=20redir?=
 =?UTF-8?q?ect=5Furl=20config=20and=20fix=20Lark=20callback=20auth?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add optional redirect_url field to auth/github and auth/lark plugin
  configs; falls back to {server}/api/auth/profile/oauth/{provider}/callback
- Add WithRedirectURI to GitHubBroker (matching LarkBroker)
- Invalidate cached brokers when redirect_url changes
- Store UserID in FlowStatus at flow-start time
- Exempt Lark callback from authMiddleware; resolve user via flow store
  state param so the redirect works without a session cookie

Assisted-by: claude-sonnet-4-6
---
 internal/admin/middleware.go  |  5 +++--
 internal/admin/oauth.go       | 38 +++++++++++++++++++++++++----------
 internal/admin/server.go      | 14 +++++++------
 internal/oauthcli/gh.go       | 16 +++++++++++----
 internal/oauthcli/lark.go     |  1 +
 internal/oauthcli/types.go    |  1 +
 plugins/auth/github/plugin.go | 13 ++++++++++++
 plugins/auth/lark/plugin.go   | 25 +++++++++++++++++------
 8 files changed, 84 insertions(+), 29 deletions(-)

diff --git a/internal/admin/middleware.go b/internal/admin/middleware.go
index d24fc6c5..13629795 100644
--- a/internal/admin/middleware.go
+++ b/internal/admin/middleware.go
@@ -41,12 +41,13 @@ func (s *Server) authMiddleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		path := r.URL.Path
 
-		// Exempt paths: login page, static assets, auth login/register/logout.
+		// Exempt paths: login page, static assets, auth endpoints, OAuth callbacks.
 		if path == "/login" ||
 			strings.HasPrefix(path, "/static/") ||
 			path == "/api/auth/login" ||
 			path == "/api/auth/register" ||
-			path == "/api/auth/logout" {
+			path == "/api/auth/logout" ||
+			path == "/api/auth/profile/oauth/lark/callback" {
 			next.ServeHTTP(w, r)
 			return
 		}
diff --git a/internal/admin/oauth.go b/internal/admin/oauth.go
index 54e0ef5f..f2707689 100644
--- a/internal/admin/oauth.go
+++ b/internal/admin/oauth.go
@@ -17,6 +17,9 @@ const (
 // It must match the redirect_uri configured in the Lark app.
 const larkCallbackPath = "/api/auth/profile/oauth/lark/callback"
 
+// ghCallbackPath is the path GitHub redirects back to after user authorization.
+const ghCallbackPath = "/api/auth/profile/oauth/github/callback"
+
 // getGitHubBroker returns the cached GitHubBroker, lazily constructing it from
 // the current plugin config. Returns an error if the plugin is not configured.
 func (s *Server) getGitHubBroker(ctx context.Context) (*oauthcli.GitHubBroker, error) {
@@ -29,15 +32,20 @@ func (s *Server) getGitHubBroker(ctx context.Context) (*oauthcli.GitHubBroker, e
 	if clientID == "" || clientSecret == "" {
 		return nil, fmt.Errorf("github OAuth app is not configured (set client_id and client_secret in auth/github plugin)")
 	}
+	redirectURI, _ := state.Config["redirect_url"].(string)
+	if redirectURI == "" {
+		redirectURI = s.corsOriginV + ghCallbackPath
+	}
 
 	s.oauthMu.Lock()
 	defer s.oauthMu.Unlock()
-	if s.ghBroker == nil || s.ghBrokerClientID != clientID {
+	if s.ghBroker == nil || s.ghBrokerClientID != clientID || s.ghBrokerRedirectURI != redirectURI {
 		s.ghBroker = oauthcli.NewGitHubBroker(oauthcli.GitHubConfig{
 			ClientID:     clientID,
 			ClientSecret: clientSecret,
-		}, s.flowStore)
+		}, s.flowStore).WithRedirectURI(redirectURI)
 		s.ghBrokerClientID = clientID
+		s.ghBrokerRedirectURI = redirectURI
 	}
 	return s.ghBroker, nil
 }
@@ -59,16 +67,21 @@ func (s *Server) getLarkBroker(ctx context.Context) (*oauthcli.LarkBroker, error
 		brand = "lark"
 	}
 
+	redirectURI, _ := state.Config["redirect_url"].(string)
+	if redirectURI == "" {
+		redirectURI = s.corsOriginV + larkCallbackPath
+	}
+
 	s.oauthMu.Lock()
 	defer s.oauthMu.Unlock()
-	if s.larkBroker == nil || s.larkBrokerAppID != appID {
-		redirectURI := s.corsOriginV + larkCallbackPath
+	if s.larkBroker == nil || s.larkBrokerAppID != appID || s.larkBrokerRedirectURI != redirectURI {
 		s.larkBroker = oauthcli.NewLarkBroker(oauthcli.LarkConfig{
 			AppID:     appID,
 			AppSecret: appSecret,
 			Brand:     brand,
 		}, s.flowStore).WithRedirectURI(redirectURI)
 		s.larkBrokerAppID = appID
+		s.larkBrokerRedirectURI = redirectURI
 	}
 	return s.larkBroker, nil
 }
@@ -294,16 +307,13 @@ func (s *Server) disconnectOAuth(w http.ResponseWriter, r *http.Request) {
 // larkOAuthCallback handles GET /api/auth/profile/oauth/lark/callback.
 // Lark redirects the browser here after the user authorizes the app.
 // Query params: code=<auth_code>&state=<flow_id>
+// This handler is exempt from authMiddleware; userID is resolved from the
+// flow store via the state param so no session cookie is required.
 func (s *Server) larkOAuthCallback(w http.ResponseWriter, r *http.Request) {
 	if s.vaultSvc == nil {
 		http.Error(w, "vault not configured", http.StatusServiceUnavailable)
 		return
 	}
-	info := UserFromContext(r.Context())
-	if info == nil {
-		http.Redirect(w, r, "/login", http.StatusFound)
-		return
-	}
 
 	code := r.URL.Query().Get("code")
 	flowID := r.URL.Query().Get("state")
@@ -312,6 +322,12 @@ func (s *Server) larkOAuthCallback(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	flow, ok := s.flowStore.Get(flowID)
+	if !ok {
+		http.Error(w, "unknown or expired flow", http.StatusBadRequest)
+		return
+	}
+
 	ctx := r.Context()
 	broker, err := s.getLarkBroker(ctx)
 	if err != nil {
@@ -319,8 +335,8 @@ func (s *Server) larkOAuthCallback(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if err := broker.Complete(ctx, s.vaultSvc, info.UserID, flowID, code); err != nil {
-		s.log.Error("lark oauth complete", "user_id", info.UserID, "flow_id", flowID, "error", err)
+	if err := broker.Complete(ctx, s.vaultSvc, flow.UserID, flowID, code); err != nil {
+		s.log.Error("lark oauth complete", "user_id", flow.UserID, "flow_id", flowID, "error", err)
 		http.Error(w, "failed to complete Lark authorization: "+err.Error(), http.StatusInternalServerError)
 		return
 	}
diff --git a/internal/admin/server.go b/internal/admin/server.go
index fe4e39f8..b9c4e5ff 100644
--- a/internal/admin/server.go
+++ b/internal/admin/server.go
@@ -38,12 +38,14 @@ type Server struct {
 	vaultSvc       *vault.Service       // optional; if nil, vault endpoints return 503
 
 	// OAuth CLI device-flow state.
-	flowStore        *oauthcli.FlowStore
-	oauthMu          sync.Mutex
-	ghBroker         *oauthcli.GitHubBroker // lazily initialised; guarded by oauthMu
-	ghBrokerClientID string                 // tracks which client_id ghBroker was built with
-	larkBroker       *oauthcli.LarkBroker   // lazily initialised; guarded by oauthMu
-	larkBrokerAppID  string                 // tracks which app_id larkBroker was built with
+	flowStore             *oauthcli.FlowStore
+	oauthMu               sync.Mutex
+	ghBroker              *oauthcli.GitHubBroker // lazily initialised; guarded by oauthMu
+	ghBrokerClientID      string                 // tracks which client_id ghBroker was built with
+	ghBrokerRedirectURI   string                 // tracks which redirect_url ghBroker was built with
+	larkBroker            *oauthcli.LarkBroker   // lazily initialised; guarded by oauthMu
+	larkBrokerAppID       string                 // tracks which app_id larkBroker was built with
+	larkBrokerRedirectURI string                 // tracks which redirect_url larkBroker was built with
 }
 
 // New creates an admin server with all API routes mounted.
diff --git a/internal/oauthcli/gh.go b/internal/oauthcli/gh.go
index 3161ccc7..ca34db71 100644
--- a/internal/oauthcli/gh.go
+++ b/internal/oauthcli/gh.go
@@ -31,10 +31,11 @@ type ghFlowSecret struct {
 
 // GitHubBroker manages GitHub device-flow sessions.
 type GitHubBroker struct {
-	cfg    GitHubConfig
-	store  *FlowStore
-	mu     sync.Mutex
-	secret map[string]*ghFlowSecret // flowID → secrets
+	cfg         GitHubConfig
+	store       *FlowStore
+	redirectURI string
+	mu          sync.Mutex
+	secret      map[string]*ghFlowSecret // flowID → secrets
 }
 
 // NewGitHubBroker constructs a GitHubBroker.
@@ -46,10 +47,16 @@ func NewGitHubBroker(cfg GitHubConfig, store *FlowStore) *GitHubBroker {
 	}
 }
 
+// WithRedirectURI returns a new broker with the given redirect URI.
+func (b *GitHubBroker) WithRedirectURI(uri string) *GitHubBroker {
+	return &GitHubBroker{cfg: b.cfg, store: b.store, redirectURI: uri, secret: b.secret}
+}
+
 func (b *GitHubBroker) oauthConfig() *oauth2.Config {
 	return &oauth2.Config{
 		ClientID:     b.cfg.ClientID,
 		ClientSecret: b.cfg.ClientSecret,
+		RedirectURL:  b.redirectURI,
 		Scopes:       ghScopes,
 		Endpoint:     github.Endpoint,
 	}
@@ -72,6 +79,7 @@ func (b *GitHubBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowS
 	status := FlowStatus{
 		Provider:        ProviderGitHub,
 		FlowID:          flowID,
+		UserID:          userID,
 		VerificationURI: da.VerificationURIComplete,
 		UserCode:        da.UserCode,
 		ExpiresAt:       expiresAt,
diff --git a/internal/oauthcli/lark.go b/internal/oauthcli/lark.go
index 3375e924..009bb897 100644
--- a/internal/oauthcli/lark.go
+++ b/internal/oauthcli/lark.go
@@ -112,6 +112,7 @@ func (b *LarkBroker) StartDeviceFlow(ctx context.Context, userID int64) (FlowSta
 	status := FlowStatus{
 		Provider:        ProviderLark,
 		FlowID:          flowID,
+		UserID:          userID,
 		VerificationURI: b.oauthConfig().AuthCodeURL(flowID),
 		ExpiresAt:       time.Now().Add(10 * time.Minute),
 		State:           FlowStatePending,
diff --git a/internal/oauthcli/types.go b/internal/oauthcli/types.go
index 25b5c77f..e5d40021 100644
--- a/internal/oauthcli/types.go
+++ b/internal/oauthcli/types.go
@@ -24,6 +24,7 @@ const (
 type FlowStatus struct {
 	Provider        Provider
 	FlowID          string
+	UserID          int64
 	VerificationURI string
 	UserCode        string
 	ExpiresAt       time.Time
diff --git a/plugins/auth/github/plugin.go b/plugins/auth/github/plugin.go
index 331cfbb4..89dde6ee 100644
--- a/plugins/auth/github/plugin.go
+++ b/plugins/auth/github/plugin.go
@@ -12,12 +12,14 @@ const PluginID = "auth/github"
 type Config struct {
 	ClientID     string `json:"client_id"`
 	ClientSecret string `json:"client_secret"`
+	RedirectURL  string `json:"redirect_url"`
 }
 
 func defaultConfig() map[string]any {
 	return map[string]any{
 		"client_id":     "",
 		"client_secret": "",
+		"redirect_url":  "",
 	}
 }
 
@@ -33,6 +35,10 @@ func configSchema() map[string]any {
 				"type":        "string",
 				"description": "GitHub OAuth app client secret.",
 			},
+			"redirect_url": map[string]any{
+				"type":        "string",
+				"description": "OAuth redirect URI registered in the GitHub app. Leave empty to use the server default: {your-server}/api/auth/profile/oauth/github/callback.",
+			},
 		},
 		"required": []any{"client_id", "client_secret"},
 	}
@@ -54,6 +60,13 @@ func decodeConfig(raw map[string]any) (Config, error) {
 		}
 		cfg.ClientSecret = s
 	}
+	if v, ok := raw["redirect_url"]; ok {
+		s, ok := v.(string)
+		if !ok {
+			return Config{}, fmt.Errorf("redirect_url: must be a string")
+		}
+		cfg.RedirectURL = s
+	}
 	return cfg, nil
 }
 
diff --git a/plugins/auth/lark/plugin.go b/plugins/auth/lark/plugin.go
index 38c14830..f1cbd879 100644
--- a/plugins/auth/lark/plugin.go
+++ b/plugins/auth/lark/plugin.go
@@ -10,16 +10,18 @@ import (
 const PluginID = "auth/lark"
 
 type Config struct {
-	AppID     string `json:"app_id"`
-	AppSecret string `json:"app_secret"`
-	Brand     string `json:"brand"`
+	AppID       string `json:"app_id"`
+	AppSecret   string `json:"app_secret"`
+	Brand       string `json:"brand"`
+	RedirectURL string `json:"redirect_url"`
 }
 
 func defaultConfig() map[string]any {
 	return map[string]any{
-		"app_id":     "",
-		"app_secret": "",
-		"brand":      "lark",
+		"app_id":       "",
+		"app_secret":   "",
+		"brand":        "lark",
+		"redirect_url": "",
 	}
 }
 
@@ -41,6 +43,10 @@ func configSchema() map[string]any {
 				"description": "Platform brand: \"lark\" (international) or \"feishu\" (China).",
 				"default":     "lark",
 			},
+			"redirect_url": map[string]any{
+				"type":        "string",
+				"description": "OAuth redirect URI registered in the Lark app. Leave empty to use the server default: {your-server}/api/auth/profile/oauth/lark/callback.",
+			},
 		},
 		"required": []any{"app_id", "app_secret", "brand"},
 	}
@@ -69,6 +75,13 @@ func decodeConfig(raw map[string]any) (Config, error) {
 		}
 		cfg.Brand = s
 	}
+	if v, ok := raw["redirect_url"]; ok {
+		s, ok := v.(string)
+		if !ok {
+			return Config{}, fmt.Errorf("redirect_url: must be a string")
+		}
+		cfg.RedirectURL = s
+	}
 	return cfg, nil
 }
 

From 7b7ac256ebf6ec6b1d02548fb8426dc97ac1f079 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 10:17:50 +0800
Subject: [PATCH 17/21] format

---
 internal/oauthcli/token_manager.go | 1 -
 1 file changed, 1 deletion(-)

diff --git a/internal/oauthcli/token_manager.go b/internal/oauthcli/token_manager.go
index 96c53616..8c404713 100644
--- a/internal/oauthcli/token_manager.go
+++ b/internal/oauthcli/token_manager.go
@@ -8,7 +8,6 @@ import (
 	"golang.org/x/oauth2"
 )
 
-
 // tokenExpirySafetyMargin is subtracted from expiry times to avoid using
 // tokens that are about to expire during a long-running operation.
 const tokenExpirySafetyMargin = 2 * time.Minute

From e8db71a91852697f35e65ac1440fc00fe576a517 Mon Sep 17 00:00:00 2001
From: Vaayne <liu.vaayne@gmail.com>
Date: Wed, 22 Apr 2026 11:57:06 +0800
Subject: [PATCH 18/21] =?UTF-8?q?=E2=9C=A8=20feat(admin):=20improve=20skil?=
 =?UTF-8?q?ls=20UI=20and=20Lark=20integration?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace file tab bar with dropdown selector in skills drawer
- Make custom agent skill rows clickable to open skills drawer
- Switch builtin skill badges to open drawer (read-only) instead of toggle
- Add openAgentSkill() for agent-scoped drawer navigation
- Update Lark builddeps and sync_builtin for device-flow OAuth
- Update docs for Feishu channel and agent templates

Assisted-by: claude-code:claude-sonnet-4-6
---
 docs/content/docs/channels/feishu.md          |   3 +-
 docs/content/docs/channels/feishu.zh.md       |   3 +-
 docs/content/docs/features/agent-templates.md |  16 +-
 .../docs/features/agent-templates.zh.md       |  16 +-
 internal/admin/ui/pages/agents.templ          |   1 +
 internal/admin/ui/pages/agents_form.templ     |  13 +-
 internal/admin/ui/pages/agents_form_templ.go  |  14 +-
 internal/admin/ui/pages/agents_templ.go       |   4 +
 internal/admin/ui/skills_drawer.templ         |  48 +++---
 internal/admin/ui/skills_drawer_templ.go      |   2 +-
 internal/admin/ui/static/js/pages/agents.js   |  36 +++--
 .../agent/runner/template/system_prompt.tmpl  |   4 +-
 internal/builddeps/lark.go                    | 151 ++++++++++++++----
 internal/builddeps/lark_test.go               |  22 ++-
 internal/config/snapshot.go                   |   7 +-
 internal/skills/sync_builtin.go               |  25 +++
 internal/skills/sync_builtin_test.go          |  39 +++++
 plugins/tools/skills/prompt.go                |  26 +--
 plugins/tools/skills/prompt_test.go           |  47 +-----
 19 files changed, 308 insertions(+), 169 deletions(-)

diff --git a/docs/content/docs/channels/feishu.md b/docs/content/docs/channels/feishu.md
index bd31f2d3..2dd7c049 100644
--- a/docs/content/docs/channels/feishu.md
+++ b/docs/content/docs/channels/feishu.md
@@ -30,8 +30,7 @@ anna now ships a generated builtin `lark` system skill, and release builds embed
 Typical setup:
 
 ```bash
-command -v lark-cli
-npm install -g @larksuite/cli
+command -v lark-cli || npm install -g @larksuite/cli
 lark-cli config init --new
 lark-cli auth login --recommend
 lark-cli auth status
diff --git a/docs/content/docs/channels/feishu.zh.md b/docs/content/docs/channels/feishu.zh.md
index 2c51c9e8..b336fce5 100644
--- a/docs/content/docs/channels/feishu.zh.md
+++ b/docs/content/docs/channels/feishu.zh.md
@@ -28,8 +28,7 @@ anna 现在会内置生成好的 `lark` system skill，发布构建也会自动
 常见初始化流程：
 
 ```bash
-command -v lark-cli
-npm install -g @larksuite/cli
+command -v lark-cli || npm install -g @larksuite/cli
 lark-cli config init --new
 lark-cli auth login --recommend
 lark-cli auth status
diff --git a/docs/content/docs/features/agent-templates.md b/docs/content/docs/features/agent-templates.md
index 0e3288c9..a6f27a4a 100644
--- a/docs/content/docs/features/agent-templates.md
+++ b/docs/content/docs/features/agent-templates.md
@@ -21,7 +21,7 @@ A template is a complete starting point for a new agent. When you click **Add ag
 
 - **Model** — provider/model pair the template recommends
 - **System prompt** — copied from the template's referenced soul
-- **Enabled builtin skills** — shown as chips on the form; togglable before save
+- **Builtin skill metadata** — retained for compatibility with older templates, but system-scope builtin skills are now always available to every agent
 
 User-supplied fields always win. You can edit every field on the form before saving, and after save the agent has no persistent link back to the template — upgrading a template does not touch existing agents.
 
@@ -46,22 +46,22 @@ Sub-agent presets describe tool-restricted workers for the `agent` delegation to
 
 Shipped sub-agents: `coder`, `researcher`, `reviewer`, `writer`.
 
-## Skills and per-agent enablement
+## Skills
 
-Every skill marked `scope='system'` is universal by design, which means naive growth of the builtin catalog would drop every skill into every agent's prompt — fast prompt bloat.
+Every skill synced into the database with `scope='system'` is available to every agent automatically.
 
-The fix: `settings_agents.enabled_builtin_skills` (JSON array of skill names). An agent's skill catalog in the prompt is:
+An agent's skill catalog in the prompt is:
 
 ```
-{always-on builtins: anna}
- ∪ {enabled_builtin_skills}
+{all system-scope builtin skills}
  ∪ {agent-scope DB skills}
  ∪ {user-scope DB skills}
+ ∪ {project skills from .agents/skills}
 ```
 
-`anna` (the self-knowledge skill) is always on. Every other builtin skill must be opted in — either via the template you picked (which sets the list for you) or by toggling chips on the agent form.
+The legacy `settings_agents.enabled_builtin_skills` field is still stored for backward compatibility with older templates and agent rows, but it no longer filters prompt visibility.
 
-Shipped skills: `anna`, `code-review`, `docs-writing`, `implementation`, `research`, `task-planning`.
+Shipped system skills live under `internal/resources/skills/system/` and are synced into `skills(scope='system')` on startup. Startup sync is authoritative: skills removed from the embedded system catalog are deleted from the database on the next sync.
 
 ## Adding a new builtin resource
 
diff --git a/docs/content/docs/features/agent-templates.zh.md b/docs/content/docs/features/agent-templates.zh.md
index c0445075..52e5e3d5 100644
--- a/docs/content/docs/features/agent-templates.zh.md
+++ b/docs/content/docs/features/agent-templates.zh.md
@@ -21,7 +21,7 @@ Anna 自带一套**内置资源目录**，让全新安装即开即用，无需
 
 - **模型** — 模板推荐的 provider/model 组合
 - **系统提示** — 复制自模板引用的 soul
-- **已启用的内置技能** — 以芯片形式显示在表单上，保存前可自由切换
+- **内置技能元数据** — 为兼容旧模板而保留，但 `scope='system'` 的内置技能现已自动对所有 agent 可用
 
 用户手动输入始终优先。所有字段在保存前都可以编辑；保存之后 agent 与模板没有任何持久关联 — 更新模板不会影响已有 agent。
 
@@ -46,22 +46,22 @@ Sub-agent 预设定义了 `agent` 委派工具使用的受限工作者（调研
 
 附带的 sub-agent：`coder`、`researcher`、`reviewer`、`writer`。
 
-## Skill 与按 agent 开关
+## Skill
 
-每个 `scope='system'` 的技能天生对所有 agent 可见，因此朴素地增长内置技能目录会把所有技能同时塞进每个 agent 的提示 — 提示体积会迅速膨胀。
+所有同步到数据库且 `scope='system'` 的技能，都会自动对所有 agent 可用。
 
-解决方式：`settings_agents.enabled_builtin_skills`（JSON 字符串数组）。agent 看到的技能目录为：
+agent 在提示里看到的技能目录为：
 
 ```
-{常驻内置：anna}
- ∪ {enabled_builtin_skills 中列出的}
+{全部 system 范围内置技能}
  ∪ {agent 范围的数据库技能}
  ∪ {user 范围的数据库技能}
+ ∪ {来自 .agents/skills 的 project 技能}
 ```
 
-`anna`（自我知识技能）永远启用。其他内置技能必须显式开启 — 通过你选择的模板（模板会替你设好）或手动切换表单上的芯片。
+历史遗留的 `settings_agents.enabled_builtin_skills` 字段仍会保留，以兼容旧模板和旧 agent 行，但它已不再参与提示可见性的过滤。
 
-附带的技能：`anna`、`code-review`、`docs-writing`、`implementation`、`research`、`task-planning`。
+附带的 system skill 位于 `internal/resources/skills/system/`，启动时会同步到 `skills(scope='system')`。启动同步是权威来源：如果某个嵌入式 system skill 已从目录中移除，那么下一次同步时也会从数据库中删除。
 
 ## 新增一个内置资源
 
diff --git a/internal/admin/ui/pages/agents.templ b/internal/admin/ui/pages/agents.templ
index 17d769e5..b0f1a858 100644
--- a/internal/admin/ui/pages/agents.templ
+++ b/internal/admin/ui/pages/agents.templ
@@ -11,6 +11,7 @@ templ AgentsPage() {
 		@agentTemplateModal()
 		@agentSkillInstallModal()
 		@agentConfirmDialog()
+		@ui.SkillsDrawer()
 	</div>
 }
 
diff --git a/internal/admin/ui/pages/agents_form.templ b/internal/admin/ui/pages/agents_form.templ
index e5be7e90..d3a2e6b3 100644
--- a/internal/admin/ui/pages/agents_form.templ
+++ b/internal/admin/ui/pages/agents_form.templ
@@ -148,14 +148,13 @@ templ agentSkillsTab() {
 	<div class="space-y-6">
 		<div x-show="builtinSkills.length > 0">
 			<p class="text-xs font-mono font-medium text-secondary uppercase tracking-wider mb-2">Builtin skills</p>
-			<p class="text-xs text-base-content/60 mb-2">Anna's self-knowledge is always on. Toggle extras for this agent.</p>
+			<p class="text-xs text-base-content/60 mb-2">System-scope builtin skills are always available to every agent.</p>
 			<div class="flex flex-wrap gap-2">
 				<template x-for="sk in builtinSkills" :key="sk.id">
 					<button
-						@click="toggleBuiltinSkill(sk.name)"
+						@click="openSystemSkill(sk.name)"
 						type="button"
-						class="badge badge-sm cursor-pointer transition-colors"
-						:class="isBuiltinSkillEnabled(sk.name) ? 'badge-primary' : 'badge-ghost'"
+						class="badge badge-sm badge-ghost cursor-pointer transition-colors hover:bg-base-200"
 						:title="sk.description"
 						x-text="sk.name"
 					></button>
@@ -173,8 +172,8 @@ templ agentSkillsTab() {
 					<div>
 						<div class="space-y-1 mb-3">
 							<template x-for="sk in agentSkills" :key="sk.id">
-								<div class="flex items-center justify-between rounded border border-base-300 px-3 py-2">
-									<div class="flex items-center gap-2 min-w-0">
+								<div class="flex items-center justify-between rounded border border-base-300 px-3 py-2 hover:bg-base-200/50 transition-colors">
+									<button @click="openAgentSkill(sk)" type="button" class="flex items-center gap-2 min-w-0 flex-1 text-left">
 										<span class="text-sm font-mono truncate" x-text="sk.name"></span>
 										<span
 											class="badge badge-xs"
@@ -186,7 +185,7 @@ templ agentSkillsTab() {
 											}"
 											x-text="sk.status"
 										></span>
-									</div>
+									</button>
 									<button @click="deleteAgentSkill(sk.id)" class="btn btn-ghost btn-xs text-error shrink-0">remove</button>
 								</div>
 							</template>
diff --git a/internal/admin/ui/pages/agents_form_templ.go b/internal/admin/ui/pages/agents_form_templ.go
index f6d933d5..ddc10da9 100644
--- a/internal/admin/ui/pages/agents_form_templ.go
+++ b/internal/admin/ui/pages/agents_form_templ.go
@@ -274,7 +274,7 @@ func agentSkillsTab() templ.Component {
 			templ_7745c5c3_Var8 = templ.NopComponent
 		}
 		ctx = templ.ClearChildren(ctx)
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 17, "<div class=\"space-y-6\"><div x-show=\"builtinSkills.length > 0\"><p class=\"text-xs font-mono font-medium text-secondary uppercase tracking-wider mb-2\">Builtin skills</p><p class=\"text-xs text-base-content/60 mb-2\">Anna's self-knowledge is always on. Toggle extras for this agent.</p><div class=\"flex flex-wrap gap-2\"><template x-for=\"sk in builtinSkills\" :key=\"sk.id\"><button @click=\"toggleBuiltinSkill(sk.name)\" type=\"button\" class=\"badge badge-sm cursor-pointer transition-colors\" :class=\"isBuiltinSkillEnabled(sk.name) ? 'badge-primary' : 'badge-ghost'\" :title=\"sk.description\" x-text=\"sk.name\"></button></template></div></div><div><p class=\"text-xs font-mono font-medium text-secondary uppercase tracking-wider mb-2\">Custom skills</p><div x-show=\"!editingId\" class=\"text-xs text-base-content/50 italic py-1\">Save the agent first to manage custom skills.</div><div x-show=\"editingId\"><template x-if=\"agentSkillsLoading\"><div class=\"py-4 flex justify-center\"><span class=\"loading loading-spinner loading-sm\"></span></div></template><template x-if=\"!agentSkillsLoading\"><div><div class=\"space-y-1 mb-3\"><template x-for=\"sk in agentSkills\" :key=\"sk.id\"><div class=\"flex items-center justify-between rounded border border-base-300 px-3 py-2\"><div class=\"flex items-center gap-2 min-w-0\"><span class=\"text-sm font-mono truncate\" x-text=\"sk.name\"></span> <span class=\"badge badge-xs\" :class=\"{\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-success': sk.status === 'active',\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-warning': sk.status === 'draft',\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-error':   sk.status === 'deprecated',\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-ghost':   !['active','draft','deprecated'].includes(sk.status)\n\t\t\t\t\t\t\t\t\t\t\t}\" x-text=\"sk.status\"></span></div><button @click=\"deleteAgentSkill(sk.id)\" class=\"btn btn-ghost btn-xs text-error shrink-0\">remove</button></div></template><div x-show=\"agentSkills.length === 0\" class=\"text-xs text-base-content/50 px-1\">No custom skills installed.</div></div><button @click=\"openSkillInstallModal()\" type=\"button\" class=\"btn btn-ghost btn-sm text-primary\">+ Install skill</button></div></template></div></div></div>")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 17, "<div class=\"space-y-6\"><div x-show=\"builtinSkills.length > 0\"><p class=\"text-xs font-mono font-medium text-secondary uppercase tracking-wider mb-2\">Builtin skills</p><p class=\"text-xs text-base-content/60 mb-2\">System-scope builtin skills are always available to every agent.</p><div class=\"flex flex-wrap gap-2\"><template x-for=\"sk in builtinSkills\" :key=\"sk.id\"><button @click=\"openSystemSkill(sk.name)\" type=\"button\" class=\"badge badge-sm badge-ghost cursor-pointer transition-colors hover:bg-base-200\" :title=\"sk.description\" x-text=\"sk.name\"></button></template></div></div><div><p class=\"text-xs font-mono font-medium text-secondary uppercase tracking-wider mb-2\">Custom skills</p><div x-show=\"!editingId\" class=\"text-xs text-base-content/50 italic py-1\">Save the agent first to manage custom skills.</div><div x-show=\"editingId\"><template x-if=\"agentSkillsLoading\"><div class=\"py-4 flex justify-center\"><span class=\"loading loading-spinner loading-sm\"></span></div></template><template x-if=\"!agentSkillsLoading\"><div><div class=\"space-y-1 mb-3\"><template x-for=\"sk in agentSkills\" :key=\"sk.id\"><div class=\"flex items-center justify-between rounded border border-base-300 px-3 py-2 hover:bg-base-200/50 transition-colors\"><button @click=\"openAgentSkill(sk)\" type=\"button\" class=\"flex items-center gap-2 min-w-0 flex-1 text-left\"><span class=\"text-sm font-mono truncate\" x-text=\"sk.name\"></span> <span class=\"badge badge-xs\" :class=\"{\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-success': sk.status === 'active',\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-warning': sk.status === 'draft',\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-error':   sk.status === 'deprecated',\n\t\t\t\t\t\t\t\t\t\t\t\t'badge-ghost':   !['active','draft','deprecated'].includes(sk.status)\n\t\t\t\t\t\t\t\t\t\t\t}\" x-text=\"sk.status\"></span></button> <button @click=\"deleteAgentSkill(sk.id)\" class=\"btn btn-ghost btn-xs text-error shrink-0\">remove</button></div></template><div x-show=\"agentSkills.length === 0\" class=\"text-xs text-base-content/50 px-1\">No custom skills installed.</div></div><button @click=\"openSkillInstallModal()\" type=\"button\" class=\"btn btn-ghost btn-sm text-primary\">+ Install skill</button></div></template></div></div></div>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
@@ -397,7 +397,7 @@ func modelComboField(label string, field string, placeholder string) templ.Compo
 		var templ_7745c5c3_Var13 string
 		templ_7745c5c3_Var13, templ_7745c5c3_Err = templ.JoinStringErrs(label)
 		if templ_7745c5c3_Err != nil {
-			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 299, Col: 53}
+			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 298, Col: 53}
 		}
 		_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var13))
 		if templ_7745c5c3_Err != nil {
@@ -420,7 +420,7 @@ func modelComboField(label string, field string, placeholder string) templ.Compo
 		var templ_7745c5c3_Var14 string
 		templ_7745c5c3_Var14, templ_7745c5c3_Err = templ.JoinStringErrs("form." + field)
 		if templ_7745c5c3_Err != nil {
-			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 306, Col: 27}
+			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 305, Col: 27}
 		}
 		_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var14))
 		if templ_7745c5c3_Err != nil {
@@ -433,7 +433,7 @@ func modelComboField(label string, field string, placeholder string) templ.Compo
 		var templ_7745c5c3_Var15 string
 		templ_7745c5c3_Var15, templ_7745c5c3_Err = templ.JoinStringErrs("form." + field + " = $event.target.value; search = $event.target.value; open = cachedModels.length > 0")
 		if templ_7745c5c3_Err != nil {
-			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 307, Col: 116}
+			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 306, Col: 116}
 		}
 		_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var15))
 		if templ_7745c5c3_Err != nil {
@@ -446,7 +446,7 @@ func modelComboField(label string, field string, placeholder string) templ.Compo
 		var templ_7745c5c3_Var16 string
 		templ_7745c5c3_Var16, templ_7745c5c3_Err = templ.JoinStringErrs(placeholder)
 		if templ_7745c5c3_Err != nil {
-			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 309, Col: 28}
+			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 308, Col: 28}
 		}
 		_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var16))
 		if templ_7745c5c3_Err != nil {
@@ -459,7 +459,7 @@ func modelComboField(label string, field string, placeholder string) templ.Compo
 		var templ_7745c5c3_Var17 string
 		templ_7745c5c3_Var17, templ_7745c5c3_Err = templ.JoinStringErrs("form." + field + " = m; open = false")
 		if templ_7745c5c3_Err != nil {
-			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 321, Col: 52}
+			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 320, Col: 52}
 		}
 		_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var17))
 		if templ_7745c5c3_Err != nil {
@@ -472,7 +472,7 @@ func modelComboField(label string, field string, placeholder string) templ.Compo
 		var templ_7745c5c3_Var18 string
 		templ_7745c5c3_Var18, templ_7745c5c3_Err = templ.JoinStringErrs("form." + field + " === m ? 'text-primary' : 'text-base-content/70'")
 		if templ_7745c5c3_Err != nil {
-			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 324, Col: 82}
+			return templ.Error{Err: templ_7745c5c3_Err, FileName: `internal/admin/ui/pages/agents_form.templ`, Line: 323, Col: 82}
 		}
 		_, templ_7745c5c3_Err = templ_7745c5c3_Buffer.WriteString(templ.EscapeString(templ_7745c5c3_Var18))
 		if templ_7745c5c3_Err != nil {
diff --git a/internal/admin/ui/pages/agents_templ.go b/internal/admin/ui/pages/agents_templ.go
index 1412e3e9..a4f71c7d 100644
--- a/internal/admin/ui/pages/agents_templ.go
+++ b/internal/admin/ui/pages/agents_templ.go
@@ -59,6 +59,10 @@ func AgentsPage() templ.Component {
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
+		templ_7745c5c3_Err = ui.SkillsDrawer().Render(ctx, templ_7745c5c3_Buffer)
+		if templ_7745c5c3_Err != nil {
+			return templ_7745c5c3_Err
+		}
 		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 3, "</div>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
diff --git a/internal/admin/ui/skills_drawer.templ b/internal/admin/ui/skills_drawer.templ
index e49ac0a8..69b41f48 100644
--- a/internal/admin/ui/skills_drawer.templ
+++ b/internal/admin/ui/skills_drawer.templ
@@ -152,31 +152,31 @@ templ SkillsDrawer() {
 								</label>
 							</div>
 						</div>
-						<!-- File tabs -->
-						<div class="px-6 pt-3 pb-2 flex items-center gap-1 flex-wrap border-b border-base-300 shrink-0">
-							<template x-for="f in (skillsDrawer.selected.files || ['SKILL.md'])" :key="f">
-								<div class="flex items-center">
-									<button
-										@click="selectDrawerFile(f)"
-										class="btn btn-xs rounded-r-none"
-										:class="skillsDrawer.activeFile === f ? 'btn-primary' : 'btn-ghost'"
-										x-text="f"
-									></button>
-									<button
-										x-show="skillsDrawer.canEdit && f !== 'SKILL.md' && skillsDrawer.activeFile === f"
-										@click.stop="deleteDrawerFile(f)"
-										class="btn btn-xs btn-ghost rounded-l-none px-1 text-error"
-										title="Delete file"
-									>✕</button>
-								</div>
-							</template>
-							<template x-if="!skillsDrawer.addingFile">
+						<!-- File selector -->
+						<div class="px-6 pt-3 pb-2 border-b border-base-300 shrink-0 space-y-2">
+							<div class="flex items-center gap-2">
+								<select
+									x-model="skillsDrawer.activeFile"
+									@change="selectDrawerFile(skillsDrawer.activeFile)"
+									class="select select-bordered select-sm font-mono text-xs w-auto max-w-sm py-0 leading-normal"
+								>
+									<template x-for="f in (skillsDrawer.selected.files || ['SKILL.md'])" :key="f">
+										<option :value="f" x-text="f"></option>
+									</template>
+								</select>
+								<div class="flex-1"></div>
+								<button
+									x-show="skillsDrawer.canEdit && skillsDrawer.activeFile !== 'SKILL.md'"
+									@click="deleteDrawerFile(skillsDrawer.activeFile)"
+									class="btn btn-ghost btn-xs text-error shrink-0"
+									title="Delete file"
+								>✕</button>
 								<button
-									x-show="skillsDrawer.canEdit"
+									x-show="skillsDrawer.canEdit && !skillsDrawer.addingFile"
 									@click="confirmAddDrawerFile()"
-									class="btn btn-xs btn-ghost text-secondary"
-								>+ Add file</button>
-							</template>
+									class="btn btn-ghost btn-xs text-secondary shrink-0"
+								>+ Add</button>
+							</div>
 							<template x-if="skillsDrawer.addingFile">
 								<div class="flex items-center gap-1">
 									<input
@@ -184,7 +184,7 @@ templ SkillsDrawer() {
 										@keydown.enter.prevent="commitAddDrawerFile()"
 										@keydown.escape="skillsDrawer.addingFile = false"
 										placeholder="reference.md"
-										class="input input-bordered input-xs w-40 font-mono"
+										class="input input-bordered input-xs flex-1 font-mono"
 										autofocus
 									/>
 									<button @click="commitAddDrawerFile()" class="btn btn-xs btn-primary">Add</button>
diff --git a/internal/admin/ui/skills_drawer_templ.go b/internal/admin/ui/skills_drawer_templ.go
index 399b2b67..97dab587 100644
--- a/internal/admin/ui/skills_drawer_templ.go
+++ b/internal/admin/ui/skills_drawer_templ.go
@@ -36,7 +36,7 @@ func SkillsDrawer() templ.Component {
 			templ_7745c5c3_Var1 = templ.NopComponent
 		}
 		ctx = templ.ClearChildren(ctx)
-		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 1, "<!-- Slide-over backdrop + panel --><div x-show=\"skillsDrawer.open\" x-cloak x-transition.opacity @keydown.escape.window=\"closeSkillsDrawer()\" class=\"fixed inset-0 z-40 bg-black/40\" @click=\"closeSkillsDrawer()\"></div><div x-show=\"skillsDrawer.open\" x-cloak x-transition:enter=\"transition ease-out duration-200\" x-transition:enter-start=\"translate-x-full\" x-transition:enter-end=\"translate-x-0\" x-transition:leave=\"transition ease-in duration-150\" x-transition:leave-start=\"translate-x-0\" x-transition:leave-end=\"translate-x-full\" class=\"fixed top-0 right-0 z-50 h-screen w-full max-w-4xl bg-base-100 shadow-2xl flex flex-col border-l border-base-300\"><!-- Header --><header class=\"px-6 py-4 border-b border-base-300 flex items-center justify-between shrink-0\"><div class=\"min-w-0\"><h2 class=\"font-semibold text-lg truncate\" x-text=\"skillsDrawer.title\"></h2><p class=\"text-xs text-secondary truncate\" x-text=\"skillsDrawer.subtitle\"></p></div><button @click=\"closeSkillsDrawer()\" class=\"btn btn-ghost btn-sm btn-circle shrink-0\">✕</button></header><!-- Body --><div class=\"flex-1 min-h-0 flex overflow-hidden\"><!-- Left: skill list --><aside class=\"w-64 shrink-0 border-r border-base-300 flex flex-col\"><div class=\"p-3 border-b border-base-300 shrink-0\"><button @click=\"openDrawerInstallModal()\" x-show=\"skillsDrawer.canEdit\" class=\"btn btn-primary btn-sm w-full\">+ Install skill</button><p x-show=\"!skillsDrawer.canEdit\" class=\"text-xs text-secondary text-center\">Read only</p></div><div class=\"flex-1 min-h-0 overflow-y-auto\"><template x-if=\"skillsDrawer.loading\"><div class=\"p-4 text-center\"><span class=\"loading loading-spinner loading-sm\"></span></div></template><template x-if=\"!skillsDrawer.loading && skillsDrawer.skills.length === 0\"><p class=\"p-4 text-xs text-secondary text-center\">No skills yet.</p></template><template x-for=\"sk in skillsDrawer.skills\" :key=\"sk.id\"><button @click=\"selectDrawerSkill(sk)\" class=\"w-full text-left px-3 py-2 border-b border-base-200 hover:bg-base-200/60 transition-colors block\" :class=\"skillsDrawer.selected && skillsDrawer.selected.id === sk.id ? 'bg-base-200' : ''\"><div class=\"text-sm font-medium truncate\" x-text=\"sk.name\"></div><div class=\"flex items-center gap-1 mt-0.5\"><span class=\"badge badge-xs\" :class=\"{\n\t\t\t\t\t\t\t\t\t\t'badge-success': sk.status === 'active',\n\t\t\t\t\t\t\t\t\t\t'badge-warning': sk.status === 'draft',\n\t\t\t\t\t\t\t\t\t\t'badge-error':   sk.status === 'deprecated',\n\t\t\t\t\t\t\t\t\t\t'badge-ghost':   !['active','draft','deprecated'].includes(sk.status),\n\t\t\t\t\t\t\t\t\t}\" x-text=\"sk.status\"></span></div></button></template></div></aside><!-- Right: editor --><section class=\"flex-1 min-w-0 flex flex-col\"><!-- No selection --><template x-if=\"!skillsDrawer.selected\"><div class=\"flex-1 flex items-center justify-center text-center px-6\"><div class=\"space-y-1\"><p class=\"text-sm font-medium\">Select a skill</p><p class=\"text-xs text-secondary\">Pick a skill on the left, or install a new one.</p></div></div></template><!-- Detail --><template x-if=\"skillsDrawer.selected\"><div class=\"flex-1 min-h-0 flex flex-col\"><!-- Metadata --><div class=\"px-6 py-4 border-b border-base-300 space-y-3 shrink-0\"><div class=\"flex items-start justify-between gap-3 flex-wrap\"><div class=\"min-w-0\"><p class=\"font-medium truncate\" x-text=\"skillsDrawer.selected.name\"></p><p class=\"font-mono text-[11px] text-secondary truncate\" x-text=\"skillsDrawer.selected.id\"></p></div><div class=\"flex items-center gap-2 shrink-0\"><button x-show=\"skillsDrawer.canEdit\" @click=\"deleteDrawerSkill()\" class=\"btn btn-ghost btn-xs text-error\">Delete skill</button> <button x-show=\"skillsDrawer.canEdit\" @click=\"saveDrawerSkill()\" :disabled=\"skillsDrawer.saving\" class=\"btn btn-primary btn-xs\"><span x-show=\"skillsDrawer.saving\" class=\"loading loading-spinner loading-xs\"></span> Save</button></div></div><div class=\"grid grid-cols-1 sm:grid-cols-2 gap-3\"><div class=\"sm:col-span-2 space-y-1\"><label class=\"text-xs font-medium text-secondary\">Description</label> <input x-model=\"skillsDrawer.selected.description\" @input=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" type=\"text\" class=\"input input-bordered input-sm w-full\"></div><div class=\"space-y-1\"><label class=\"text-xs font-medium text-secondary\">Status</label> <select x-model=\"skillsDrawer.selected.status\" @change=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" class=\"select select-bordered select-sm w-full\"><option value=\"active\">active</option> <option value=\"draft\">draft</option> <option value=\"deprecated\">deprecated</option></select></div><label class=\"flex items-end gap-2 cursor-pointer\"><input x-model=\"skillsDrawer.selected.disable_model_invocation\" @change=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" type=\"checkbox\" class=\"toggle toggle-primary toggle-sm\"> <span class=\"label-text text-xs\">Disable model invocation</span></label></div></div><!-- File tabs --><div class=\"px-6 pt-3 pb-2 flex items-center gap-1 flex-wrap border-b border-base-300 shrink-0\"><template x-for=\"f in (skillsDrawer.selected.files || ['SKILL.md'])\" :key=\"f\"><div class=\"flex items-center\"><button @click=\"selectDrawerFile(f)\" class=\"btn btn-xs rounded-r-none\" :class=\"skillsDrawer.activeFile === f ? 'btn-primary' : 'btn-ghost'\" x-text=\"f\"></button> <button x-show=\"skillsDrawer.canEdit && f !== 'SKILL.md' && skillsDrawer.activeFile === f\" @click.stop=\"deleteDrawerFile(f)\" class=\"btn btn-xs btn-ghost rounded-l-none px-1 text-error\" title=\"Delete file\">✕</button></div></template><template x-if=\"!skillsDrawer.addingFile\"><button x-show=\"skillsDrawer.canEdit\" @click=\"confirmAddDrawerFile()\" class=\"btn btn-xs btn-ghost text-secondary\">+ Add file</button></template><template x-if=\"skillsDrawer.addingFile\"><div class=\"flex items-center gap-1\"><input x-model=\"skillsDrawer.newFileName\" @keydown.enter.prevent=\"commitAddDrawerFile()\" @keydown.escape=\"skillsDrawer.addingFile = false\" placeholder=\"reference.md\" class=\"input input-bordered input-xs w-40 font-mono\" autofocus> <button @click=\"commitAddDrawerFile()\" class=\"btn btn-xs btn-primary\">Add</button> <button @click=\"skillsDrawer.addingFile = false\" class=\"btn btn-xs btn-ghost\">Cancel</button></div></template></div><!-- Editor --><div class=\"flex-1 min-h-0 p-6 pt-3 flex flex-col\"><template x-if=\"skillsDrawer.fileLoading\"><div class=\"flex items-center justify-center flex-1 text-sm text-secondary\">Loading…</div></template><template x-if=\"!skillsDrawer.fileLoading\"><textarea x-model=\"skillsDrawer.fileContent\" @input=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" class=\"textarea textarea-bordered flex-1 min-h-0 w-full font-mono text-xs resize-none\" spellcheck=\"false\"></textarea></template></div></div></template></section></div><!-- Install modal (nested) --><template x-if=\"skillsDrawer.installModalOpen\"><div class=\"absolute inset-0 z-10 flex items-center justify-center bg-black/40\"><div class=\"card bg-base-100 shadow-xl w-full max-w-xl mx-4\" @click.away=\"skillsDrawer.installModalOpen = false\"><div class=\"card-body gap-4\"><!-- Stage 1: search --><template x-if=\"skillsDrawer.installStage === 'search'\"><div class=\"space-y-3\"><div class=\"flex items-center justify-between\"><h3 class=\"font-semibold text-base\">Install skill</h3><button @click=\"skillsDrawer.installModalOpen = false\" class=\"btn btn-ghost btn-sm btn-circle\">✕</button></div><input x-model=\"skillsDrawer.searchQuery\" @input.debounce.300ms=\"doDrawerSearch()\" placeholder=\"e.g. react-typescript\" class=\"input input-bordered w-full\" autofocus><template x-if=\"skillsDrawer.searching\"><div class=\"py-4 text-center\"><span class=\"loading loading-spinner loading-md\"></span></div></template><template x-if=\"!skillsDrawer.searching && skillsDrawer.searchResults.length > 0\"><div class=\"border border-base-300 rounded-lg overflow-y-auto max-h-64 divide-y divide-base-200\"><template x-for=\"s in skillsDrawer.searchResults\" :key=\"s.source + '@' + s.skillId\"><button @click=\"pickDrawerSearchResult(s)\" class=\"w-full text-left px-3 py-2 hover:bg-base-200/60 transition-colors\"><div class=\"flex items-center justify-between gap-2\"><span class=\"font-mono text-xs font-medium truncate\" x-text=\"s.source + '@' + s.skillId\"></span> <span class=\"text-[11px] text-secondary shrink-0\" x-text=\"s.installs + ' installs'\"></span></div><p class=\"text-xs text-secondary truncate mt-0.5\" x-text=\"s.name\"></p></button></template></div></template><template x-if=\"!skillsDrawer.searching && skillsDrawer.searchQuery && skillsDrawer.searchResults.length === 0\"><p class=\"text-xs text-secondary text-center py-4\">No skills found.</p></template></div></template><!-- Stage 2: confirm --><template x-if=\"skillsDrawer.installStage === 'confirm'\"><div class=\"space-y-3\"><div class=\"flex items-center justify-between\"><h3 class=\"font-semibold text-base\">Confirm install</h3><button @click=\"skillsDrawer.installModalOpen = false\" class=\"btn btn-ghost btn-sm btn-circle\">✕</button></div><div class=\"space-y-1\"><label class=\"text-xs font-medium text-secondary\">Source</label><div class=\"input input-bordered input-sm w-full flex items-center font-mono text-xs bg-base-200/50 cursor-default\" x-text=\"skillsDrawer.installSource\"></div></div><p class=\"text-xs text-secondary\">Installs into <span class=\"font-mono font-medium\" x-text=\"skillsDrawer.scope\"></span><template x-if=\"skillsDrawer.scope === 'agent'\"><span>scope for agent <span class=\"font-mono font-medium\" x-text=\"skillsDrawer.agentID\"></span></span></template><template x-if=\"skillsDrawer.scope === 'user'\"><span>scope for<template x-if=\"skillsDrawer.userID\"><span>user <span class=\"font-mono font-medium\" x-text=\"skillsDrawer.userID\"></span></span></template><template x-if=\"!skillsDrawer.userID\"><span>your account</span></template></span></template>.</p><div class=\"modal-action\"><button @click=\"skillsDrawer.installStage = 'search'\" class=\"btn btn-ghost btn-sm\">Back</button> <button @click=\"doDrawerInstall()\" :disabled=\"skillsDrawer.installing\" class=\"btn btn-primary btn-sm\"><span x-show=\"skillsDrawer.installing\" class=\"loading loading-spinner loading-xs\"></span> Install</button></div></div></template></div></div></div></template></div>")
+		templ_7745c5c3_Err = templruntime.WriteString(templ_7745c5c3_Buffer, 1, "<!-- Slide-over backdrop + panel --><div x-show=\"skillsDrawer.open\" x-cloak x-transition.opacity @keydown.escape.window=\"closeSkillsDrawer()\" class=\"fixed inset-0 z-40 bg-black/40\" @click=\"closeSkillsDrawer()\"></div><div x-show=\"skillsDrawer.open\" x-cloak x-transition:enter=\"transition ease-out duration-200\" x-transition:enter-start=\"translate-x-full\" x-transition:enter-end=\"translate-x-0\" x-transition:leave=\"transition ease-in duration-150\" x-transition:leave-start=\"translate-x-0\" x-transition:leave-end=\"translate-x-full\" class=\"fixed top-0 right-0 z-50 h-screen w-full max-w-4xl bg-base-100 shadow-2xl flex flex-col border-l border-base-300\"><!-- Header --><header class=\"px-6 py-4 border-b border-base-300 flex items-center justify-between shrink-0\"><div class=\"min-w-0\"><h2 class=\"font-semibold text-lg truncate\" x-text=\"skillsDrawer.title\"></h2><p class=\"text-xs text-secondary truncate\" x-text=\"skillsDrawer.subtitle\"></p></div><button @click=\"closeSkillsDrawer()\" class=\"btn btn-ghost btn-sm btn-circle shrink-0\">✕</button></header><!-- Body --><div class=\"flex-1 min-h-0 flex overflow-hidden\"><!-- Left: skill list --><aside class=\"w-64 shrink-0 border-r border-base-300 flex flex-col\"><div class=\"p-3 border-b border-base-300 shrink-0\"><button @click=\"openDrawerInstallModal()\" x-show=\"skillsDrawer.canEdit\" class=\"btn btn-primary btn-sm w-full\">+ Install skill</button><p x-show=\"!skillsDrawer.canEdit\" class=\"text-xs text-secondary text-center\">Read only</p></div><div class=\"flex-1 min-h-0 overflow-y-auto\"><template x-if=\"skillsDrawer.loading\"><div class=\"p-4 text-center\"><span class=\"loading loading-spinner loading-sm\"></span></div></template><template x-if=\"!skillsDrawer.loading && skillsDrawer.skills.length === 0\"><p class=\"p-4 text-xs text-secondary text-center\">No skills yet.</p></template><template x-for=\"sk in skillsDrawer.skills\" :key=\"sk.id\"><button @click=\"selectDrawerSkill(sk)\" class=\"w-full text-left px-3 py-2 border-b border-base-200 hover:bg-base-200/60 transition-colors block\" :class=\"skillsDrawer.selected && skillsDrawer.selected.id === sk.id ? 'bg-base-200' : ''\"><div class=\"text-sm font-medium truncate\" x-text=\"sk.name\"></div><div class=\"flex items-center gap-1 mt-0.5\"><span class=\"badge badge-xs\" :class=\"{\n\t\t\t\t\t\t\t\t\t\t'badge-success': sk.status === 'active',\n\t\t\t\t\t\t\t\t\t\t'badge-warning': sk.status === 'draft',\n\t\t\t\t\t\t\t\t\t\t'badge-error':   sk.status === 'deprecated',\n\t\t\t\t\t\t\t\t\t\t'badge-ghost':   !['active','draft','deprecated'].includes(sk.status),\n\t\t\t\t\t\t\t\t\t}\" x-text=\"sk.status\"></span></div></button></template></div></aside><!-- Right: editor --><section class=\"flex-1 min-w-0 flex flex-col\"><!-- No selection --><template x-if=\"!skillsDrawer.selected\"><div class=\"flex-1 flex items-center justify-center text-center px-6\"><div class=\"space-y-1\"><p class=\"text-sm font-medium\">Select a skill</p><p class=\"text-xs text-secondary\">Pick a skill on the left, or install a new one.</p></div></div></template><!-- Detail --><template x-if=\"skillsDrawer.selected\"><div class=\"flex-1 min-h-0 flex flex-col\"><!-- Metadata --><div class=\"px-6 py-4 border-b border-base-300 space-y-3 shrink-0\"><div class=\"flex items-start justify-between gap-3 flex-wrap\"><div class=\"min-w-0\"><p class=\"font-medium truncate\" x-text=\"skillsDrawer.selected.name\"></p><p class=\"font-mono text-[11px] text-secondary truncate\" x-text=\"skillsDrawer.selected.id\"></p></div><div class=\"flex items-center gap-2 shrink-0\"><button x-show=\"skillsDrawer.canEdit\" @click=\"deleteDrawerSkill()\" class=\"btn btn-ghost btn-xs text-error\">Delete skill</button> <button x-show=\"skillsDrawer.canEdit\" @click=\"saveDrawerSkill()\" :disabled=\"skillsDrawer.saving\" class=\"btn btn-primary btn-xs\"><span x-show=\"skillsDrawer.saving\" class=\"loading loading-spinner loading-xs\"></span> Save</button></div></div><div class=\"grid grid-cols-1 sm:grid-cols-2 gap-3\"><div class=\"sm:col-span-2 space-y-1\"><label class=\"text-xs font-medium text-secondary\">Description</label> <input x-model=\"skillsDrawer.selected.description\" @input=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" type=\"text\" class=\"input input-bordered input-sm w-full\"></div><div class=\"space-y-1\"><label class=\"text-xs font-medium text-secondary\">Status</label> <select x-model=\"skillsDrawer.selected.status\" @change=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" class=\"select select-bordered select-sm w-full\"><option value=\"active\">active</option> <option value=\"draft\">draft</option> <option value=\"deprecated\">deprecated</option></select></div><label class=\"flex items-end gap-2 cursor-pointer\"><input x-model=\"skillsDrawer.selected.disable_model_invocation\" @change=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" type=\"checkbox\" class=\"toggle toggle-primary toggle-sm\"> <span class=\"label-text text-xs\">Disable model invocation</span></label></div></div><!-- File selector --><div class=\"px-6 pt-3 pb-2 border-b border-base-300 shrink-0 space-y-2\"><div class=\"flex items-center gap-2\"><select x-model=\"skillsDrawer.activeFile\" @change=\"selectDrawerFile(skillsDrawer.activeFile)\" class=\"select select-bordered select-sm font-mono text-xs w-auto max-w-sm py-0 leading-normal\"><template x-for=\"f in (skillsDrawer.selected.files || ['SKILL.md'])\" :key=\"f\"><option :value=\"f\" x-text=\"f\"></option></template></select><div class=\"flex-1\"></div><button x-show=\"skillsDrawer.canEdit && skillsDrawer.activeFile !== 'SKILL.md'\" @click=\"deleteDrawerFile(skillsDrawer.activeFile)\" class=\"btn btn-ghost btn-xs text-error shrink-0\" title=\"Delete file\">✕</button> <button x-show=\"skillsDrawer.canEdit && !skillsDrawer.addingFile\" @click=\"confirmAddDrawerFile()\" class=\"btn btn-ghost btn-xs text-secondary shrink-0\">+ Add</button></div><template x-if=\"skillsDrawer.addingFile\"><div class=\"flex items-center gap-1\"><input x-model=\"skillsDrawer.newFileName\" @keydown.enter.prevent=\"commitAddDrawerFile()\" @keydown.escape=\"skillsDrawer.addingFile = false\" placeholder=\"reference.md\" class=\"input input-bordered input-xs flex-1 font-mono\" autofocus> <button @click=\"commitAddDrawerFile()\" class=\"btn btn-xs btn-primary\">Add</button> <button @click=\"skillsDrawer.addingFile = false\" class=\"btn btn-xs btn-ghost\">Cancel</button></div></template></div><!-- Editor --><div class=\"flex-1 min-h-0 p-6 pt-3 flex flex-col\"><template x-if=\"skillsDrawer.fileLoading\"><div class=\"flex items-center justify-center flex-1 text-sm text-secondary\">Loading…</div></template><template x-if=\"!skillsDrawer.fileLoading\"><textarea x-model=\"skillsDrawer.fileContent\" @input=\"markDrawerDirty()\" :disabled=\"!skillsDrawer.canEdit\" class=\"textarea textarea-bordered flex-1 min-h-0 w-full font-mono text-xs resize-none\" spellcheck=\"false\"></textarea></template></div></div></template></section></div><!-- Install modal (nested) --><template x-if=\"skillsDrawer.installModalOpen\"><div class=\"absolute inset-0 z-10 flex items-center justify-center bg-black/40\"><div class=\"card bg-base-100 shadow-xl w-full max-w-xl mx-4\" @click.away=\"skillsDrawer.installModalOpen = false\"><div class=\"card-body gap-4\"><!-- Stage 1: search --><template x-if=\"skillsDrawer.installStage === 'search'\"><div class=\"space-y-3\"><div class=\"flex items-center justify-between\"><h3 class=\"font-semibold text-base\">Install skill</h3><button @click=\"skillsDrawer.installModalOpen = false\" class=\"btn btn-ghost btn-sm btn-circle\">✕</button></div><input x-model=\"skillsDrawer.searchQuery\" @input.debounce.300ms=\"doDrawerSearch()\" placeholder=\"e.g. react-typescript\" class=\"input input-bordered w-full\" autofocus><template x-if=\"skillsDrawer.searching\"><div class=\"py-4 text-center\"><span class=\"loading loading-spinner loading-md\"></span></div></template><template x-if=\"!skillsDrawer.searching && skillsDrawer.searchResults.length > 0\"><div class=\"border border-base-300 rounded-lg overflow-y-auto max-h-64 divide-y divide-base-200\"><template x-for=\"s in skillsDrawer.searchResults\" :key=\"s.source + '@' + s.skillId\"><button @click=\"pickDrawerSearchResult(s)\" class=\"w-full text-left px-3 py-2 hover:bg-base-200/60 transition-colors\"><div class=\"flex items-center justify-between gap-2\"><span class=\"font-mono text-xs font-medium truncate\" x-text=\"s.source + '@' + s.skillId\"></span> <span class=\"text-[11px] text-secondary shrink-0\" x-text=\"s.installs + ' installs'\"></span></div><p class=\"text-xs text-secondary truncate mt-0.5\" x-text=\"s.name\"></p></button></template></div></template><template x-if=\"!skillsDrawer.searching && skillsDrawer.searchQuery && skillsDrawer.searchResults.length === 0\"><p class=\"text-xs text-secondary text-center py-4\">No skills found.</p></template></div></template><!-- Stage 2: confirm --><template x-if=\"skillsDrawer.installStage === 'confirm'\"><div class=\"space-y-3\"><div class=\"flex items-center justify-between\"><h3 class=\"font-semibold text-base\">Confirm install</h3><button @click=\"skillsDrawer.installModalOpen = false\" class=\"btn btn-ghost btn-sm btn-circle\">✕</button></div><div class=\"space-y-1\"><label class=\"text-xs font-medium text-secondary\">Source</label><div class=\"input input-bordered input-sm w-full flex items-center font-mono text-xs bg-base-200/50 cursor-default\" x-text=\"skillsDrawer.installSource\"></div></div><p class=\"text-xs text-secondary\">Installs into <span class=\"font-mono font-medium\" x-text=\"skillsDrawer.scope\"></span><template x-if=\"skillsDrawer.scope === 'agent'\"><span>scope for agent <span class=\"font-mono font-medium\" x-text=\"skillsDrawer.agentID\"></span></span></template><template x-if=\"skillsDrawer.scope === 'user'\"><span>scope for<template x-if=\"skillsDrawer.userID\"><span>user <span class=\"font-mono font-medium\" x-text=\"skillsDrawer.userID\"></span></span></template><template x-if=\"!skillsDrawer.userID\"><span>your account</span></template></span></template>.</p><div class=\"modal-action\"><button @click=\"skillsDrawer.installStage = 'search'\" class=\"btn btn-ghost btn-sm\">Back</button> <button @click=\"doDrawerInstall()\" :disabled=\"skillsDrawer.installing\" class=\"btn btn-primary btn-sm\"><span x-show=\"skillsDrawer.installing\" class=\"loading loading-spinner loading-xs\"></span> Install</button></div></div></template></div></div></div></template></div>")
 		if templ_7745c5c3_Err != nil {
 			return templ_7745c5c3_Err
 		}
diff --git a/internal/admin/ui/static/js/pages/agents.js b/internal/admin/ui/static/js/pages/agents.js
index efa650f6..9b49d1b2 100644
--- a/internal/admin/ui/static/js/pages/agents.js
+++ b/internal/admin/ui/static/js/pages/agents.js
@@ -1,4 +1,5 @@
 import { api } from '/static/js/api.js'
+import { skillsDrawerMixin } from '/static/js/components/skills_drawer.js'
 
 function parseChannelConfig(raw) {
   try { return JSON.parse(raw || '{}') } catch { return {} }
@@ -16,6 +17,7 @@ function normalizeChannel(ch) {
 
 export function register(Alpine) {
   Alpine.data('agentsPage', () => ({
+    ...skillsDrawerMixin(),
     agents: [],
     channels: [],
     cachedModels: [],
@@ -143,18 +145,18 @@ export function register(Alpine) {
         .catch(e => { this.selectedSoulID = ''; this.$store.toast.show(e.message, 'error') })
     },
 
-    // --- Builtin skill toggles ---
+    // --- Builtin skill details ---
 
-    toggleBuiltinSkill(name) {
-      const list = this.form.enabled_builtin_skills || []
-      const idx = list.indexOf(name)
-      this.form.enabled_builtin_skills = idx >= 0
-        ? list.filter((_, i) => i !== idx)
-        : [...list, name]
-    },
-
-    isBuiltinSkillEnabled(name) {
-      return (this.form.enabled_builtin_skills || []).includes(name)
+    async openSystemSkill(name) {
+      await this.openSkillsDrawer({
+        title: 'System skills',
+        subtitle: 'Read only · available to every agent',
+        scope: 'system',
+        useAdminAPI: true,
+        canEdit: false,
+      })
+      const skill = this.skillsDrawer.skills.find(sk => sk.name === name)
+      if (skill) await this.selectDrawerSkill(skill)
     },
 
     // --- Auth / users ---
@@ -394,6 +396,18 @@ export function register(Alpine) {
 
     // --- Custom skills ---
 
+    async openAgentSkill(sk) {
+      await this.openSkillsDrawer({
+        title: 'Agent skills',
+        subtitle: 'Skills installed for this agent',
+        scope: 'agent',
+        agentID: this.editingId,
+        canEdit: this.canEditAgent(this.agents.find(a => a.id === this.editingId)),
+      })
+      const skill = this.skillsDrawer.skills.find(s => s.id === sk.id)
+      if (skill) await this.selectDrawerSkill(skill)
+    },
+
     async loadAgentSkills(agentId) {
       if (!agentId) return
       this.agentSkillsLoading = true
diff --git a/internal/agent/runner/template/system_prompt.tmpl b/internal/agent/runner/template/system_prompt.tmpl
index b44cfe27..e69d240b 100644
--- a/internal/agent/runner/template/system_prompt.tmpl
+++ b/internal/agent/runner/template/system_prompt.tmpl
@@ -8,7 +8,9 @@
 - `write`: Create a new file or fully overwrite an existing one
 - `edit`: Surgical string replacement in a file (old text must match exactly)
 - `bash`: Run shell commands — git, system tools, package managers, etc. Do NOT use bash to read/write files; use the dedicated tools above
-  - Built-in CLI tools available in bash: `fd` (fast file finder), `rg` (ripgrep, fast regex search). Prefer these over `find` and `grep`
+  - Common CLI tools available in Anna sandbox bash sessions: `fd` (fast file finder), `rg` (ripgrep), `mise`, `tap`, `gh`, and `lark-cli`. Prefer `fd`/`rg` over `find`/`grep`.
+  - Anna's docker sandbox image also includes standard runtimes/package managers such as `node`/`npm`, `python3`, `uv`, and `bun`.
+  - Do not claim a CLI is unavailable without first checking with `command -v <name>` or an equivalent probe.
 - `memory`: Manage persistent knowledge across sessions. See the Memories section below for file scope rules
 - `scheduler`: Create, list, and remove scheduled or one-time jobs
 - `skills`: Load, search, install, list, remove, create, and update local skills
diff --git a/internal/builddeps/lark.go b/internal/builddeps/lark.go
index b83dc467..82561598 100644
--- a/internal/builddeps/lark.go
+++ b/internal/builddeps/lark.go
@@ -1,6 +1,7 @@
 package builddeps
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"log/slog"
@@ -9,6 +10,7 @@ import (
 	"regexp"
 	"sort"
 	"strings"
+	"text/template"
 
 	git "github.com/go-git/go-git/v5"
 	"github.com/go-git/go-git/v5/plumbing"
@@ -27,6 +29,8 @@ type larkSkillDoc struct {
 	File        string
 }
 
+const annaLarkSharedDescription = "飞书/Lark CLI 共享基础（Anna 适配版）：说明 Anna 会话中的 wrapper + 环境变量认证模型、`--as user` / `--as bot` 选择、scope / Permission denied 处理，以及何时才需要回退到上游 `config init` / `auth login` 流程。"
+
 func SyncSystemSkills(ctx context.Context, cfg Config) error {
 	if err := syncLarkSkill(ctx, cfg); err != nil {
 		return err
@@ -133,6 +137,10 @@ func migrateLarkSkill(skillDir, refsDir string) (larkSkillDoc, error) {
 	content := string(raw)
 	meta, _ := parseLarkFrontmatter(content)
 	updated := updateLarkMarkdownReferences(content, skillName)
+	if skillName == "lark-shared" {
+		meta.Description = annaLarkSharedDescription
+		updated = adaptLarkSharedForAnna(updated)
+	}
 	if err := AtomicWriteFile(filepath.Join(refsDir, skillName+".md"), []byte(updated), 0o644); err != nil {
 		return larkSkillDoc{}, fmt.Errorf("write migrated skill markdown: %w", err)
 	}
@@ -209,34 +217,119 @@ func updateLarkMarkdownReferences(content, skillName string) string {
 	return content
 }
 
+func adaptLarkSharedForAnna(content string) string {
+	const annaIntro = `## Anna 会话中的运行方式（优先遵循本节）
+
+在 Anna 的沙盒会话里，
+` + "`lark-cli`" + ` 走的是 **wrapper + 环境变量注入** 模式，不是上游文档默认假设的“先 ` + "`config init`" + `，再 ` + "`auth login`" + `”本地配置模式。
+
+- 直接运行 ` + "`lark-cli ...`" + ` 即可。Anna 会把会话级 wrapper（通常位于 ` + "`.anna/bin/lark-cli`" + `）放到 ` + "`PATH`" + ` 前面，再转发到真实二进制（通常是 ` + "`$ANNA_HOME/bin/lark-cli`" + `，也可能是宿主机 ` + "`PATH`" + ` 上的 ` + "`lark-cli`" + `）。
+- Anna 会在会话启动时注入 ` + "`LARK_ACCESS_TOKEN`" + `、` + "`LARK_APP_ID`" + `、` + "`LARK_BRAND`" + `。因此 **在 Anna 会话里默认不要先执行 ` + "`lark-cli config init`" + ` 或 ` + "`lark-cli auth login`" + `**。
+- 把后续文档里所有“先 ` + "`auth login --domain`" + ` / ` + "`auth login --scope`" + `”的要求，映射为：**确认 Anna Profile → OAuth CLI Credentials 已连接 Lark，所需 scope 已在 Lark 应用侧开通，然后开启一个新的 Anna 会话重试**。
+- 如果用户只是想在自己机器上单独配置一个**脱离 Anna** 的 ` + "`lark-cli`" + `，那才回退到上游原生的 ` + "`config init`" + ` / ` + "`auth login`" + ` 流程。
+
+## Anna 中的身份选择
+
+| 身份 | 在 Anna 中如何获得 | 适用场景 |
+|------|------------------|---------|
+| user 用户身份 | Anna 注入运行时用户令牌；优先使用 ` + "`--as user`" + `（或命令默认身份） | 访问用户自己的日历、云文档、任务、邮箱等个人资源 |
+| bot 应用身份 | 需要用户在 Anna 之外显式准备 app 配置 / tenant token；Anna 当前**不自动注入** bot 所需的 app secret 或 config 文件 | 仅在用户明确说明已完成这套手动配置时使用 |
+
+### 身份选择原则
+
+- **默认优先 user**：大多数日历、云空间、文档、任务、邮箱等工作区请求，本质上都是“代表当前用户操作自己的资源”。
+- **不要擅自假设 bot 可用**：如果文档或任务要求 ` + "`--as bot`" + `、` + "`tenant_access_token`" + `、appSecret 或本地 config 文件，而当前会话只有 Anna 注入的 user 运行时环境，就应先停下来说明这是**Anna 当前未自动接线**的手动配置路径。
+- **Bot 看不到用户私有资源**：即便用户自己在 Anna 外部完成了 bot 配置，` + "`--as bot`" + ` 也仍然看不到用户的私有日历、个人云文档、邮箱等资源。
+
+## Anna 中的认证与提权处理
+
+### 未连接、过期或认证失败
+
+- 如果 ` + "`lark-cli`" + ` 提示未登录、缺少 access token、401/expired，先让用户到 **Profile → OAuth CLI Credentials** 连接或重新连接 Lark。
+- Lark user access token 约 2 小时过期；Anna 只在**会话启动时**刷新。已连接但中途过期时，直接开启一个新的 Anna 会话。
+- 重新开启会话后仍失败，说明 refresh token 也可能失效或授权被撤销；此时应让用户断开并重新连接 Lark，而不是在会话里继续尝试 ` + "`auth login`" + `。
+
+### 权限不足 / scope 不足
+
+- 先查看错误里的 ` + "`permission_violations`" + `、` + "`console_url`" + `、` + "`hint`" + `。
+- 如果缺的是**应用 scope**，把 ` + "`console_url`" + ` 提供给用户或管理员，让他们去 Lark 开发者后台开通对应权限。
+- 应用 scope 开通后，在 Anna 会话里**不要**继续执行 ` + "`lark-cli auth login --scope ...`" + `；应让用户按需重新连接 Lark，并开启一个新的 Anna 会话后再重试。
+- 只有当用户明确要求“配置一套独立于 Anna 的本地 ` + "`lark-cli`" + ` 环境”时，才执行上游文档里的 ` + "`config init`" + ` / ` + "`auth login`" + ` 指令。`
+
+	content = rewriteLarkDescription(content, annaLarkSharedDescription)
+	start := strings.Index(content, "## 配置初始化")
+	end := strings.Index(content, "## 更新检查")
+	if start >= 0 && end > start {
+		return content[:start] + annaIntro + "\n\n" + content[end:]
+	}
+	if idx := strings.Index(content, "# lark-cli 共享规则"); idx >= 0 {
+		idx += len("# lark-cli 共享规则")
+		return content[:idx] + "\n\n" + annaIntro + content[idx:]
+	}
+	return content + "\n\n" + annaIntro + "\n"
+}
+
+func rewriteLarkDescription(content, description string) string {
+	return regexp.MustCompile(`(?m)^description:\s*".*"$`).ReplaceAllString(content, `description: "`+description+`"`)
+}
+
+var larkAggregateTemplate = template.Must(template.New("lark-aggregate").Funcs(template.FuncMap{
+	"escPipe": func(s string) string {
+		if s == "" {
+			return "-"
+		}
+		return strings.ReplaceAll(s, "|", "\\|")
+	},
+}).Parse(`---
+name: lark
+description: |
+  Lark/Feishu CLI skills for Anna sessions. Covers workspace operations — calendar,
+  docs, tasks, mail, and messenger — via the lark-cli tool. In Anna, lark-cli runs
+  under a wrapper + env-var auth model: LARK_ACCESS_TOKEN, LARK_APP_ID, and
+  LARK_BRAND are injected at session start; no manual config init or auth login is
+  needed. Always read lark-shared first for identity selection (--as user vs --as
+  bot), scope / permission-denied handling, token refresh, and the Anna-specific
+  rules that override upstream documentation.
+tags: [lark, feishu, workspace]
+metadata:
+  source_repo: larksuite/cli
+  source_ref: "{{.SourceRef}}"
+  generated: true
+---
+
+# Lark
+
+This skill aggregates Lark/Feishu CLI modules synced from ` + "`larksuite/cli`" + ` and adapted for Anna sessions.
+
+**Anna auth model** — ` + "`lark-cli`" + ` runs via a session wrapper that injects ` + "`LARK_ACCESS_TOKEN`" + `, ` + "`LARK_APP_ID`" + `, and ` + "`LARK_BRAND`" + ` at startup. Do not run ` + "`lark-cli config init`" + ` or ` + "`lark-cli auth login`" + ` unless the user explicitly wants a standalone local setup outside Anna.
+
+**Identity** — default to ` + "`--as user`" + ` for personal resources (calendar, docs, tasks, mail). ` + "`--as bot`" + ` requires manual app configuration outside Anna and cannot see user-private resources.
+
+**Token expiry** — user access tokens expire after ~2 hours. If mid-session auth fails, open a new Anna session. If that also fails, reconnect Lark under Profile → OAuth CLI Credentials.
+
+## Modules
+
+| Module | Description | Reference |
+| --- | --- | --- |
+{{- range .Docs}}
+| {{.Name}} | {{escPipe .Description}} | [references/{{.File}}](./references/{{.File}}) |
+{{- end}}
+
+## Usage
+
+1. Read [references/lark-shared.md](./references/lark-shared.md) first — it defines auth rules, identity selection, and scope handling that apply to every module.
+2. Identify the module matching the capability you need (calendar, docs, tasks, mail, messenger, etc.).
+3. Read the module's reference file before executing any command — it lists available subcommands, required flags, and known permission constraints.
+4. If a command returns a permission or scope error, consult the ` + "`permission_violations`" + ` and ` + "`console_url`" + ` fields in the error before retrying.
+`))
+
 func renderLarkAggregate(docs []larkSkillDoc, sourceRef string) string {
-	var b strings.Builder
-	b.WriteString("---\n")
-	b.WriteString("name: lark\n")
-	b.WriteString("description: Aggregated Lark CLI skills synced from larksuite/cli.\n")
-	b.WriteString("tags: [lark, feishu, workspace]\n")
-	b.WriteString("metadata:\n")
-	b.WriteString("  source_repo: larksuite/cli\n")
-	b.WriteString("  source_ref: \"")
-	b.WriteString(sourceRef)
-	b.WriteString("\"\n")
-	b.WriteString("  generated: true\n")
-	b.WriteString("---\n\n")
-	b.WriteString("# Lark\n\n")
-	b.WriteString("This builtin skill aggregates upstream Lark CLI skills from `larksuite/cli`. Read `lark-shared` first for auth, permissions, and shared command rules.\n\n")
-	b.WriteString("## Skills\n\n")
-	b.WriteString("| Skill | Description | File |\n")
-	b.WriteString("| --- | --- | --- |\n")
-	for _, doc := range docs {
-		desc := strings.ReplaceAll(doc.Description, "|", "\\|")
-		if desc == "" {
-			desc = "-"
-		}
-		fmt.Fprintf(&b, "| %s | %s | [references/%s](./references/%s) |\n", doc.Name, desc, doc.File, doc.File)
-	}
-	b.WriteString("\n## Usage\n\n")
-	b.WriteString("1. Start with [references/lark-shared.md](./references/lark-shared.md).\n")
-	b.WriteString("2. Pick the module that matches the workspace capability you need.\n")
-	b.WriteString("3. Read the referenced command docs before executing any Lark CLI command.\n")
-	return b.String()
+	var buf bytes.Buffer
+	if err := larkAggregateTemplate.Execute(&buf, struct {
+		Docs      []larkSkillDoc
+		SourceRef string
+	}{Docs: docs, SourceRef: sourceRef}); err != nil {
+		panic(fmt.Sprintf("renderLarkAggregate: %v", err))
+	}
+	return buf.String()
 }
diff --git a/internal/builddeps/lark_test.go b/internal/builddeps/lark_test.go
index cd50a124..3e1b4022 100644
--- a/internal/builddeps/lark_test.go
+++ b/internal/builddeps/lark_test.go
@@ -37,7 +37,13 @@ func TestUpdateLarkMarkdownReferences(t *testing.T) {
 
 func TestGenerateLarkSkill(t *testing.T) {
 	src := t.TempDir()
-	writeSkillFixture(t, filepath.Join(src, "lark-shared"), "lark-shared", "Shared setup", "Auth in ./references/auth.md")
+	writeSkillFixture(t, filepath.Join(src, "lark-shared"), "lark-shared", "Shared setup", strings.Join([]string{
+		"## 配置初始化",
+		"run lark-cli config init --new",
+		"",
+		"## 更新检查",
+		"npm update -g @larksuite/cli",
+	}, "\n"))
 	writeSkillFixture(t, filepath.Join(src, "lark-doc"), "lark-doc", "Docs module", "See ../lark-shared/SKILL.md")
 	dest := filepath.Join(t.TempDir(), "lark")
 	if err := GenerateLarkSkill(src, dest, "test-ref"); err != nil {
@@ -54,6 +60,9 @@ func TestGenerateLarkSkill(t *testing.T) {
 	if !strings.Contains(mainStr, "references/lark-shared.md") || !strings.Contains(mainStr, "references/lark-doc.md") {
 		t.Fatalf("aggregate skill missing reference links:\n%s", mainStr)
 	}
+	if !strings.Contains(mainStr, annaLarkSharedDescription) {
+		t.Fatalf("aggregate skill missing Anna-specific lark-shared description:\n%s", mainStr)
+	}
 	child, err := os.ReadFile(filepath.Join(dest, "references", "lark-doc.md"))
 	if err != nil {
 		t.Fatal(err)
@@ -61,6 +70,17 @@ func TestGenerateLarkSkill(t *testing.T) {
 	if !strings.Contains(string(child), "./lark-shared.md") {
 		t.Fatalf("expected rewritten child markdown, got:\n%s", string(child))
 	}
+	shared, err := os.ReadFile(filepath.Join(dest, "references", "lark-shared.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	sharedStr := string(shared)
+	if !strings.Contains(sharedStr, "Anna 会话中的运行方式") || !strings.Contains(sharedStr, "Profile → OAuth CLI Credentials") {
+		t.Fatalf("expected Anna-specific shared skill guidance, got:\n%s", sharedStr)
+	}
+	if strings.Contains(sharedStr, "run lark-cli config init --new") {
+		t.Fatalf("expected upstream config-init section to be replaced, got:\n%s", sharedStr)
+	}
 	ref, err := os.ReadFile(filepath.Join(dest, "references", "lark-shared", "auth.md"))
 	if err != nil {
 		t.Fatal(err)
diff --git a/internal/config/snapshot.go b/internal/config/snapshot.go
index 9b00ac45..ce94b70a 100644
--- a/internal/config/snapshot.go
+++ b/internal/config/snapshot.go
@@ -33,9 +33,10 @@ type Snapshot struct {
 	SystemPrompt string // agent's base system prompt from DB
 	Soul         string // agent's default soul from DB (fallback for all users)
 
-	// EnabledBuiltinSkills is the per-agent list of builtin skill names that
-	// appear in the prompt catalog. The always-on "anna" skill is visible to
-	// every agent regardless of this list.
+	// EnabledBuiltinSkills is retained for backward compatibility with older
+	// templates and agent rows. System-scope builtin skills are now always
+	// visible to every agent, so this list no longer affects prompt catalog
+	// visibility.
 	EnabledBuiltinSkills []string
 
 	Runner     RunnerConfig
diff --git a/internal/skills/sync_builtin.go b/internal/skills/sync_builtin.go
index 564261ae..29f79aed 100644
--- a/internal/skills/sync_builtin.go
+++ b/internal/skills/sync_builtin.go
@@ -109,12 +109,37 @@ func SyncBuiltin(ctx context.Context, store *SQLiteStore, builtinFS fs.FS) error
 		return fmt.Errorf("sync_builtin: read root: %w", err)
 	}
 
+	desired := make(map[string]struct{}, len(skillRoots))
 	for _, skillRoot := range skillRoots {
+		desired[path.Base(skillRoot)] = struct{}{}
 		if err := syncBuiltinSkill(ctx, store, builtinFS, skillRoot); err != nil {
 			slog.ErrorContext(ctx, "sync_builtin: failed to sync skill", "path", skillRoot, "err", err)
 			return fmt.Errorf("sync_builtin: skill %q: %w", skillRoot, err)
 		}
 	}
+	if err := deleteRemovedSystemSkills(ctx, store, desired); err != nil {
+		return fmt.Errorf("sync_builtin: delete removed system skills: %w", err)
+	}
+	return nil
+}
+
+func deleteRemovedSystemSkills(ctx context.Context, store *SQLiteStore, desired map[string]struct{}) error {
+	rows, err := store.q.ListAllSkills(ctx)
+	if err != nil {
+		return fmt.Errorf("list all skills: %w", err)
+	}
+	for _, row := range rows {
+		if row.Scope != "system" {
+			continue
+		}
+		if _, ok := desired[row.Name]; ok {
+			continue
+		}
+		if err := store.Delete(ctx, row.ID); err != nil {
+			return fmt.Errorf("delete skill %q (%s): %w", row.Name, row.ID, err)
+		}
+		slog.InfoContext(ctx, "sync_builtin: deleted removed system skill", "name", row.Name, "id", row.ID)
+	}
 	return nil
 }
 
diff --git a/internal/skills/sync_builtin_test.go b/internal/skills/sync_builtin_test.go
index 37c73f74..afeaf32a 100644
--- a/internal/skills/sync_builtin_test.go
+++ b/internal/skills/sync_builtin_test.go
@@ -183,4 +183,43 @@ func TestSyncBuiltin(t *testing.T) {
 			t.Fatalf("references/a.md = %q, want nested ref", ref)
 		}
 	})
+
+	t.Run("removed system skills are deleted on full sync", func(t *testing.T) {
+		store, db := newTestStore(t)
+		userID, _ := seedFixtures(t, db)
+		initialFS := fstest.MapFS{
+			"system/foo/SKILL.md": {Data: []byte(testSkillMD("foo skill"))},
+			"system/bar/SKILL.md": {Data: []byte("---\nname: bar\ndescription: bar skill\nstatus: active\n---\n\n# Bar\n")},
+		}
+		if err := SyncBuiltin(ctx, store, initialFS); err != nil {
+			t.Fatalf("initial SyncBuiltin: %v", err)
+		}
+
+		if _, err := store.Create(ctx, Skill{
+			Scope:       "user",
+			UserID:      userID,
+			Name:        "user-kept",
+			Description: "user skill",
+			Status:      "active",
+		}, map[string]string{MainFile: "# User"}); err != nil {
+			t.Fatalf("create user skill: %v", err)
+		}
+
+		reducedFS := fstest.MapFS{
+			"system/foo/SKILL.md": {Data: []byte(testSkillMD("foo skill"))},
+		}
+		if err := SyncBuiltin(ctx, store, reducedFS); err != nil {
+			t.Fatalf("second SyncBuiltin: %v", err)
+		}
+
+		if sk, err := store.Resolve(ctx, "bar", ViewContext{}); err != nil || sk != nil {
+			t.Fatalf("expected removed system skill bar to be deleted, got sk=%v err=%v", sk, err)
+		}
+		if sk, err := store.Resolve(ctx, "foo", ViewContext{}); err != nil || sk == nil {
+			t.Fatalf("expected foo to remain, got sk=%v err=%v", sk, err)
+		}
+		if sk, err := store.Resolve(ctx, "user-kept", ViewContext{UserID: userID}); err != nil || sk == nil {
+			t.Fatalf("expected non-system skill to remain, got sk=%v err=%v", sk, err)
+		}
+	})
 }
diff --git a/plugins/tools/skills/prompt.go b/plugins/tools/skills/prompt.go
index c21871e3..817a2bc7 100644
--- a/plugins/tools/skills/prompt.go
+++ b/plugins/tools/skills/prompt.go
@@ -7,11 +7,6 @@ import (
 	pkgplugins "github.com/vaayne/anna/pkg/plugins"
 )
 
-// alwaysOnBuiltinSkill is the one builtin skill visible to every agent
-// regardless of the per-agent enabled_builtin_skills list. It carries anna's
-// self-knowledge.
-const alwaysOnBuiltinSkill = "anna"
-
 func BuildPromptSection(ctx context.Context, build pkgplugins.SystemPromptContext) (pkgplugins.SystemPromptSection, error) {
 	if build.Platform == nil {
 		return pkgplugins.SystemPromptSection{}, nil
@@ -31,21 +26,8 @@ func BuildPromptSection(ctx context.Context, build pkgplugins.SystemPromptContex
 		return pkgplugins.SystemPromptSection{}, err
 	}
 
-	// Filter system-scope builtin skills to the per-agent allowlist (plus the
-	// always-on "anna" self-knowledge skill). Agent/user/project skills pass
-	// through — they are already owned, not part of the shared catalog.
-	allowedBuiltin := make(map[string]bool, len(build.EnabledBuiltinSkills)+1)
-	allowedBuiltin[alwaysOnBuiltinSkill] = true
-	for _, name := range build.EnabledBuiltinSkills {
-		allowedBuiltin[name] = true
-	}
-	filtered := make([]pkgplugins.Skill, 0, len(dbSkills))
-	for _, s := range dbSkills {
-		if s.Scope == "system" && !allowedBuiltin[s.Name] {
-			continue
-		}
-		filtered = append(filtered, s)
-	}
+	// System-scope skills are always available to every agent. Agent/user/project
+	// skills keep their existing visibility rules.
 
 	// Merge project skills from filesystem (project > user > agent > system precedence).
 	projSkills, _, _ := ListProjectSkills(build.ProjectRoot)
@@ -53,9 +35,9 @@ func BuildPromptSection(ctx context.Context, build pkgplugins.SystemPromptContex
 	for _, s := range projSkills {
 		projNames[s.Name] = true
 	}
-	all := make([]pkgplugins.Skill, 0, len(projSkills)+len(filtered))
+	all := make([]pkgplugins.Skill, 0, len(projSkills)+len(dbSkills))
 	all = append(all, projSkills...)
-	for _, s := range filtered {
+	for _, s := range dbSkills {
 		if !projNames[s.Name] {
 			all = append(all, s)
 		}
diff --git a/plugins/tools/skills/prompt_test.go b/plugins/tools/skills/prompt_test.go
index 90154a8f..276f5577 100644
--- a/plugins/tools/skills/prompt_test.go
+++ b/plugins/tools/skills/prompt_test.go
@@ -122,12 +122,10 @@ func TestBuildPromptSectionNilPlatform(t *testing.T) {
 	}
 }
 
-func TestBuildPromptSectionFiltersSystemScopeByAllowlist(t *testing.T) {
+func TestBuildPromptSectionAlwaysIncludesSystemSkills(t *testing.T) {
 	store, userID, _ := newTestSkillStore(t)
 	ctx := context.Background()
 
-	// Seed three system-scope skills: "anna" (always-on), "code-review" (allowlisted),
-	// and "research" (should be hidden when not in allowlist).
 	for _, name := range []string{"anna", "code-review", "research"} {
 		if _, err := store.Create(ctx, pkgplugins.Skill{
 			Scope:       "system",
@@ -138,7 +136,6 @@ func TestBuildPromptSectionFiltersSystemScopeByAllowlist(t *testing.T) {
 			t.Fatalf("create %s: %v", name, err)
 		}
 	}
-	// Seed one user skill so the user lane still passes through.
 	if _, err := store.Create(ctx, pkgplugins.Skill{
 		Scope:       "user",
 		UserID:      userID,
@@ -158,45 +155,9 @@ func TestBuildPromptSectionFiltersSystemScopeByAllowlist(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(section.Content, "<name>anna</name>") {
-		t.Fatalf("anna should always appear: %s", section.Content)
-	}
-	if !strings.Contains(section.Content, "<name>code-review</name>") {
-		t.Fatalf("code-review should appear (allowlisted): %s", section.Content)
-	}
-	if strings.Contains(section.Content, "<name>research</name>") {
-		t.Fatalf("research should be hidden (not in allowlist): %s", section.Content)
-	}
-	if !strings.Contains(section.Content, "<name>user-skill</name>") {
-		t.Fatalf("user skill should pass through the filter: %s", section.Content)
-	}
-}
-
-func TestBuildPromptSectionBlankAllowlistShowsOnlyAnna(t *testing.T) {
-	store, userID, _ := newTestSkillStore(t)
-	ctx := context.Background()
-	for _, name := range []string{"anna", "code-review"} {
-		if _, err := store.Create(ctx, pkgplugins.Skill{
-			Scope:       "system",
-			Name:        name,
-			Description: name + " skill",
-			Status:      "active",
-		}, map[string]string{pkgplugins.SkillMainFile: "# " + name}); err != nil {
-			t.Fatalf("create %s: %v", name, err)
+	for _, name := range []string{"anna", "code-review", "research", "user-skill"} {
+		if !strings.Contains(section.Content, "<name>"+name+"</name>") {
+			t.Fatalf("expected %s in prompt content: %s", name, section.Content)
 		}
 	}
-	platform := &skillStorePlatform{store: store}
-	section, err := BuildPromptSection(ctx, pkgplugins.SystemPromptContext{
-		Platform: platform,
-		UserID:   userID,
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(section.Content, "<name>anna</name>") {
-		t.Fatalf("anna should appear with empty allowlist: %s", section.Content)
-	}
-	if strings.Contains(section.Content, "<name>code-review</name>") {
-		t.Fatalf("code-review should not appear with empty allowlist: %s", section.Content)
-	}
 }

From c8d0f45de8a7f9a95b897abca725ab6880ea0279 Mon Sep 17 00:00:00 2001
From: Vaayne <vaayne@mbp14.local>
Date: Wed, 22 Apr 2026 14:46:24 +0800
Subject: [PATCH 19/21] =?UTF-8?q?=E2=9C=A8=20feat(admin):=20add=20URL-base?=
 =?UTF-8?q?d=20routing=20for=20session=20detail=20view?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sessions are now accessible via /sessions/<session_id>, enabling
shareable deep links. Navigation between list and detail views
updates the browser URL via history.pushState.

Assisted-by: claude-code:claude-sonnet-4-6
---
 internal/admin/routes.go                      |  1 +
 internal/admin/ui/static/js/pages/sessions.js | 16 +++++++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/internal/admin/routes.go b/internal/admin/routes.go
index 179c5e05..52f3e5ee 100644
--- a/internal/admin/routes.go
+++ b/internal/admin/routes.go
@@ -72,6 +72,7 @@ func (s *Server) registerPageRoutes() {
 	s.mux.HandleFunc("GET /channels", s.pageChannels)
 	s.mux.Handle("GET /users", s.adminOnlyMiddleware(http.HandlerFunc(s.pageUsers)))
 	s.mux.HandleFunc("GET /sessions", s.pageSessions)
+	s.mux.HandleFunc("GET /sessions/{sessionID}", s.pageSessions)
 	s.mux.HandleFunc("GET /scheduler", s.pageScheduler)
 	s.mux.Handle("GET /plugins", s.adminOnlyMiddleware(http.HandlerFunc(s.pagePlugins)))
 	s.mux.HandleFunc("GET /profile", s.pageProfile)
diff --git a/internal/admin/ui/static/js/pages/sessions.js b/internal/admin/ui/static/js/pages/sessions.js
index 4f0e3f26..7606925a 100644
--- a/internal/admin/ui/static/js/pages/sessions.js
+++ b/internal/admin/ui/static/js/pages/sessions.js
@@ -20,12 +20,22 @@ export function register(Alpine) {
 
     async init() {
       await Promise.all([this.loadSessions(), this.loadTools()])
+      const sessionID = this._sessionIDFromURL()
+      if (sessionID) {
+        await this.openSession(sessionID, false)
+      }
     },
 
     formatTime(ts) {
       return formatTime(ts)
     },
 
+    _sessionIDFromURL() {
+      const parts = window.location.pathname.split('/')
+      // pathname: /sessions/<id> → parts: ['', 'sessions', '<id>']
+      return parts.length >= 3 && parts[1] === 'sessions' ? decodeURIComponent(parts[2]) : ''
+    },
+
     async loadSessions() {
       try {
         this.sessions = await api('GET', '/api/sessions') || []
@@ -34,7 +44,7 @@ export function register(Alpine) {
       }
     },
 
-    async openSession(sessionID) {
+    async openSession(sessionID, pushState = true) {
       this.sessionMessagesLoading = true
       this.sessionMessages = []
       this.sessionSystemPrompt = ''
@@ -47,6 +57,9 @@ export function register(Alpine) {
         ])
         this.sessionMessages = msgs || []
         if (pr && pr.system_prompt) this.sessionSystemPrompt = pr.system_prompt
+        if (pushState) {
+          history.pushState({ sessionID }, '', '/sessions/' + enc)
+        }
       } catch (e) {
         this.$store.toast.show(e.message, 'error')
       } finally {
@@ -71,6 +84,7 @@ export function register(Alpine) {
       this.sessionSystemPrompt = ''
       this.showTools = false
       this.showSystemPrompt = false
+      history.pushState(null, '', '/sessions')
     },
   }))
 }

From 12051a3f0b5a0cbeb04f8dfd0b1636bd2cdc4a28 Mon Sep 17 00:00:00 2001
From: Vaayne <vaayne@mbp14.local>
Date: Wed, 22 Apr 2026 14:48:36 +0800
Subject: [PATCH 20/21] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20remove?=
 =?UTF-8?q?=20macOS=20sandbox-exec=20and=20update=20oauthcli/lark=20deps?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Drop Seatbelt sandbox-exec from macOS local backend; commands now run
  directly on the host OS. Update docs and tests accordingly.
- Update cli-oauth docs with redirect_url config notes.
- Refactor lark.go and oauthcli token_manager; add token_manager tests.

Assisted-by: claude-code:claude-sonnet-4-6
---
 .../docs/core/sandbox-backend-abstraction.md  | 20 ++---
 .../core/sandbox-backend-abstraction.zh.md    | 20 ++---
 docs/content/docs/features/cli-oauth.md       |  3 +
 docs/content/docs/features/cli-oauth.zh.md    |  2 +-
 internal/builddeps/lark.go                    |  9 +-
 internal/oauthcli/token_manager.go            |  9 +-
 internal/oauthcli/token_manager_test.go       | 44 ++++++++++
 plugins/sandbox/local/session.go              |  7 +-
 plugins/sandbox/local/session_darwin.go       | 68 +++------------
 plugins/sandbox/local/session_darwin_test.go  | 84 +++++++------------
 10 files changed, 121 insertions(+), 145 deletions(-)
 create mode 100644 internal/oauthcli/token_manager_test.go

diff --git a/docs/content/docs/core/sandbox-backend-abstraction.md b/docs/content/docs/core/sandbox-backend-abstraction.md
index 56d4c77c..7f2b1516 100644
--- a/docs/content/docs/core/sandbox-backend-abstraction.md
+++ b/docs/content/docs/core/sandbox-backend-abstraction.md
@@ -4,11 +4,11 @@ title: Sandbox Backend Abstraction
 
 ## Status
 
-Implemented. Docker is the recommended sandbox backend. A local backend is also available for Docker-free environments with OS-level hardening. Anna's execution boundary is described by `pkg/sandbox` contracts, with runner-facing registry wiring in `internal/sandbox`.
+Implemented. Docker is the recommended sandbox backend. A local backend is also available for Docker-free environments; Linux keeps OS-level hardening, while macOS currently runs local commands directly on the host without additional sandboxing. Anna's execution boundary is described by `pkg/sandbox` contracts, with runner-facing registry wiring in `internal/sandbox`.
 
 ## Purpose
 
-The sandbox abstraction exists so runner code, plugin wiring, and tool execution do not depend on concrete backend types. All sandboxed execution runs through a Docker container. Docker is required; Anna fails closed when the Docker daemon is unavailable at session-create time.
+The sandbox abstraction exists so runner code, plugin wiring, and tool execution do not depend on concrete backend types. Execution always runs through the active backend selected by the runner. Docker provides the strongest isolation; the local backend is a host-execution fallback for environments where Docker is unavailable or undesirable.
 
 The top-level model is:
 
@@ -58,9 +58,9 @@ The local backend runs commands directly on the host OS. It is intended for envi
 | Process group kill + rlimits | All Unix | `SIGKILL` on process group; `RLIMIT_FSIZE`, `RLIMIT_NOFILE`, `RLIMIT_CPU` via `prlimit(2)` |
 | Filesystem + network isolation | Linux (bwrap available) | `bwrap` — workspace bind-mounted to `/workspace`; rest of FS read-only; optional `--unshare-net` |
 | Network isolation only | Linux (no bwrap) | `unshare --net` — new network namespace, no outbound connectivity |
-| Filesystem + network policy | macOS | `sandbox-exec` Seatbelt profile — write restricted to workspace; network per policy |
+| No additional local isolation | macOS | Commands run directly on the host OS; filesystem and network policy are not enforced |
 
-The local backend uses a **fail-closed** strategy: if a required isolation tool is missing, session creation fails with an actionable error message rather than running unconfined.
+The local backend uses a **fail-closed** strategy on Linux: if a required isolation tool is missing, session creation fails with an actionable error message rather than running unconfined. On macOS, no extra sandboxing tool is currently applied.
 
 #### Installing dependencies
 
@@ -78,8 +78,8 @@ pacman -S bubblewrap
 
 `unshare` (network-only fallback) is part of `util-linux` and is present on virtually all Linux systems.
 
-**macOS — sandbox-exec:**
-Built into macOS. No installation required. Note: `sandbox-exec` has been informally deprecated since macOS 10.15 (Catalina). It remains functional but may be removed in a future macOS release.
+**macOS:**
+No additional dependency is required. The current local backend runs commands directly on the host OS without applying a macOS-specific sandbox.
 
 **Windows:** Not supported. Use the Docker backend.
 
@@ -91,14 +91,14 @@ On Linux with `bwrap`, the agent always sees its workspace at `/workspace` regar
 
 Per-agent sandbox configuration is limited to network policy (mode and allowlist). Each agent independently controls whether its sandbox allows outbound network access and which hosts are reachable.
 
-Network modes supported by the Docker backend:
+Network modes supported by Docker and by the Linux local backend:
 
 | Mode        | Description                          |
 | ----------- | ------------------------------------ |
 | `disabled`  | No outbound network access (default) |
 | `allow_all` | Unrestricted outbound access         |
 
-The `whitelist` mode is removed. Anna validates the configured mode at session-create time and fails closed if the backend cannot enforce it.
+The `whitelist` mode is removed. Docker and the Linux local backend validate the configured mode at session-create time and fail closed if the backend cannot enforce it. The macOS local backend currently ignores network policy and runs with host network access.
 
 ## Current Architecture
 
@@ -108,7 +108,7 @@ The runner creates a `sandbox.Session` for each run and keeps ownership of its l
 
 ### Backend resolution
 
-The Docker backend self-registers in `internal/sandbox` via `init()`. `pkg/sandbox.Registry.CreateSession` iterates registered factories in registration order and uses the first available factory that supports the policy. With only one factory registered, this always selects Docker or fails.
+The runner resolves the active backend from plugin state and dispatches to a backend-specific factory. Built-in factories currently support `docker` and `local`.
 
 ### Execution-time mediation
 
@@ -122,7 +122,7 @@ All local execution paths that must obey sandbox policy are mediated through the
 
 ### stdio-MCP benefit
 
-`Session.StartProcess` is fully supported by the Docker backend on every run. This means MCP stdio transports work uniformly across all platforms without requiring platform-specific subprocess handling.
+`Session.StartProcess` is supported by both built-in backends. Docker gives stdio MCP servers a dedicated container process namespace; the local backend starts them directly on the host OS.
 
 ### Non-runner filesystem access
 
diff --git a/docs/content/docs/core/sandbox-backend-abstraction.zh.md b/docs/content/docs/core/sandbox-backend-abstraction.zh.md
index aa121965..94f822c2 100644
--- a/docs/content/docs/core/sandbox-backend-abstraction.zh.md
+++ b/docs/content/docs/core/sandbox-backend-abstraction.zh.md
@@ -4,11 +4,11 @@ title: 沙箱后端抽象
 
 ## 状态
 
-已实现。Docker 是推荐的沙箱后端。本地后端也可用于无 Docker 环境，并应用了操作系统级加固措施。Anna 的执行边界由 `pkg/sandbox` 契约描述，runner 侧注册配置位于 `internal/sandbox`。
+已实现。Docker 是推荐的沙箱后端。本地后端也可用于无 Docker 环境；Linux 保留操作系统级加固，而 macOS 当前会直接在宿主机上运行本地命令，不再附加额外沙箱。Anna 的执行边界由 `pkg/sandbox` 契约描述，runner 侧注册配置位于 `internal/sandbox`。
 
 ## 目的
 
-沙箱抽象的目的是使 runner 代码、插件配置和工具执行不依赖于具体的后端类型。所有沙箱化执行都在 Docker 容器中运行。Docker 是必要条件；当 Docker 守护进程在会话创建时不可用时，Anna 会拒绝失败（fail closed）。
+沙箱抽象的目的是使 runner 代码、插件配置和工具执行不依赖于具体的后端类型。执行总是通过 runner 选中的活动后端进行。Docker 提供最强隔离；本地后端则是在 Docker 不可用或不想使用时的宿主机执行回退方案。
 
 顶层模型：
 
@@ -58,9 +58,9 @@ Docker 提供完整的容器级进程、文件系统和网络隔离。Docker 守
 | 进程组终止 + 资源限制 | 所有 Unix | 对进程组发送 `SIGKILL`；通过 `prlimit(2)` 设置 `RLIMIT_FSIZE`、`RLIMIT_NOFILE`、`RLIMIT_CPU` |
 | 文件系统 + 网络隔离 | Linux（bwrap 可用） | `bwrap` — 工作区绑定挂载到 `/workspace`；其余文件系统只读；可选 `--unshare-net` |
 | 仅网络隔离 | Linux（无 bwrap） | `unshare --net` — 新建网络命名空间，无出站连接 |
-| 文件系统 + 网络策略 | macOS | `sandbox-exec` Seatbelt 配置文件 — 写入限制在工作区；网络按策略控制 |
+| 无额外本地隔离 | macOS | 命令直接在宿主机 OS 上运行；不强制执行文件系统和网络策略 |
 
-本地后端采用**拒绝失败**策略：如果所需的隔离工具缺失，会话创建失败并返回包含操作建议的错误信息，而非在无隔离状态下运行。
+本地后端在 Linux 上采用**拒绝失败**策略：如果所需的隔离工具缺失，会话创建失败并返回包含操作建议的错误信息，而非在无隔离状态下运行。macOS 当前不再附加额外沙箱工具。
 
 #### 安装依赖
 
@@ -78,8 +78,8 @@ pacman -S bubblewrap
 
 `unshare`（仅网络隔离的备用方案）是 `util-linux` 的一部分，在几乎所有 Linux 系统上均已存在。
 
-**macOS — sandbox-exec：**
-macOS 内置，无需安装。注意：`sandbox-exec` 自 macOS 10.15（Catalina）起已被非正式弃用，仍可使用，但可能在未来的 macOS 版本中被移除。
+**macOS：**
+无需额外依赖。当前本地后端直接在宿主机 OS 上运行命令，不应用特定于 macOS 的沙箱。
 
 **Windows：** 不支持，请使用 Docker 后端。
 
@@ -91,14 +91,14 @@ macOS 内置，无需安装。注意：`sandbox-exec` 自 macOS 10.15（Catalina
 
 每个代理的沙箱配置仅限于网络策略（模式和允许列表）。每个代理独立控制其沙箱是否允许出站网络访问以及哪些主机可达。
 
-Docker 后端支持的网络模式：
+Docker 后端以及 Linux 本地后端支持的网络模式：
 
 | 模式        | 描述                         |
 | ----------- | ---------------------------- |
 | `disabled`  | 禁止所有出站网络访问（默认） |
 | `allow_all` | 不受限制的出站访问           |
 
-`whitelist` 模式已移除。Anna 在会话创建时验证已配置的模式，如果后端无法强制执行则拒绝失败。
+`whitelist` 模式已移除。Docker 和 Linux 本地后端会在会话创建时验证已配置的模式，如果后端无法强制执行则拒绝失败。macOS 本地后端当前会忽略网络策略并使用宿主机网络访问。
 
 ## 当前架构
 
@@ -108,7 +108,7 @@ runner 为每次运行创建一个 `sandbox.Session` 并持有其生命周期所
 
 ### 后端解析
 
-Docker 后端通过 `init()` 在 `internal/sandbox` 中自注册。`pkg/sandbox.Registry.CreateSession` 按注册顺序迭代已注册的工厂，使用第一个可用且支持该策略的工厂。由于只注册了一个工厂，这总是选择 Docker 或失败。
+runner 会根据插件状态解析当前活动后端，并分派到对应的后端工厂。内置工厂当前支持 `docker` 和 `local`。
 
 ### 执行时中介
 
@@ -122,7 +122,7 @@ Docker 后端通过 `init()` 在 `internal/sandbox` 中自注册。`pkg/sandbox.
 
 ### stdio-MCP 优势
 
-Docker 后端在每次运行时完全支持 `Session.StartProcess`。这意味着 MCP stdio 传输在所有平台上均可统一工作，无需特定于平台的子进程处理。
+两个内置后端都支持 `Session.StartProcess`。Docker 为 stdio MCP 服务器提供独立的容器进程命名空间；本地后端则直接在宿主机上启动这些进程。
 
 ### 非 runner 文件系统访问
 
diff --git a/docs/content/docs/features/cli-oauth.md b/docs/content/docs/features/cli-oauth.md
index 923f211d..734a59c7 100644
--- a/docs/content/docs/features/cli-oauth.md
+++ b/docs/content/docs/features/cli-oauth.md
@@ -35,6 +35,9 @@ You can disconnect at any time by clicking **Disconnect** next to the provider.
 After connecting, raw `gh` and `lark-cli` commands work inside agent sandbox sessions
 without any additional configuration. Anna prepends a wrapper directory to `PATH` so
 that every `gh` or `lark-cli` invocation automatically receives the correct credentials.
+For `lark-cli`, Anna injects `LARKSUITE_CLI_USER_ACCESS_TOKEN`,
+`LARKSUITE_CLI_APP_ID`, and `LARKSUITE_CLI_BRAND`, so no per-session `config init`
+is required.
 
 Example (issued by the agent inside a bash tool call):
 
diff --git a/docs/content/docs/features/cli-oauth.zh.md b/docs/content/docs/features/cli-oauth.zh.md
index 082e472f..881d651a 100644
--- a/docs/content/docs/features/cli-oauth.zh.md
+++ b/docs/content/docs/features/cli-oauth.zh.md
@@ -26,7 +26,7 @@ CLI OAuth 功能允许 Agent 在沙盒会话中直接使用 `gh`（GitHub CLI）
 
 ## 使用 CLI 工具
 
-连接成功后，Agent 在沙盒会话中可以直接运行 `gh` 和 `lark-cli` 命令，无需任何额外配置。Anna 会将包装脚本目录添加到 `PATH` 的最前面，使每次调用都自动获得正确的认证凭据。
+连接成功后，Agent 在沙盒会话中可以直接运行 `gh` 和 `lark-cli` 命令，无需任何额外配置。Anna 会将包装脚本目录添加到 `PATH` 的最前面，使每次调用都自动获得正确的认证凭据。对于 `lark-cli`，Anna 会注入 `LARKSUITE_CLI_USER_ACCESS_TOKEN`、`LARKSUITE_CLI_APP_ID` 和 `LARKSUITE_CLI_BRAND`，因此不需要在每个会话里再执行 `config init`。
 
 示例（由 Agent 在 bash 工具调用中执行）：
 
diff --git a/internal/builddeps/lark.go b/internal/builddeps/lark.go
index 82561598..543fec94 100644
--- a/internal/builddeps/lark.go
+++ b/internal/builddeps/lark.go
@@ -224,7 +224,7 @@ func adaptLarkSharedForAnna(content string) string {
 ` + "`lark-cli`" + ` 走的是 **wrapper + 环境变量注入** 模式，不是上游文档默认假设的“先 ` + "`config init`" + `，再 ` + "`auth login`" + `”本地配置模式。
 
 - 直接运行 ` + "`lark-cli ...`" + ` 即可。Anna 会把会话级 wrapper（通常位于 ` + "`.anna/bin/lark-cli`" + `）放到 ` + "`PATH`" + ` 前面，再转发到真实二进制（通常是 ` + "`$ANNA_HOME/bin/lark-cli`" + `，也可能是宿主机 ` + "`PATH`" + ` 上的 ` + "`lark-cli`" + `）。
-- Anna 会在会话启动时注入 ` + "`LARK_ACCESS_TOKEN`" + `、` + "`LARK_APP_ID`" + `、` + "`LARK_BRAND`" + `。因此 **在 Anna 会话里默认不要先执行 ` + "`lark-cli config init`" + ` 或 ` + "`lark-cli auth login`" + `**。
+- Anna 会在会话启动时注入 ` + "`LARKSUITE_CLI_USER_ACCESS_TOKEN`" + `、` + "`LARKSUITE_CLI_APP_ID`" + `、` + "`LARKSUITE_CLI_BRAND`" + `。因此 **在 Anna 会话里默认不要先执行 ` + "`lark-cli config init`" + ` 或 ` + "`lark-cli auth login`" + `**。
 - 把后续文档里所有“先 ` + "`auth login --domain`" + ` / ` + "`auth login --scope`" + `”的要求，映射为：**确认 Anna Profile → OAuth CLI Credentials 已连接 Lark，所需 scope 已在 Lark 应用侧开通，然后开启一个新的 Anna 会话重试**。
 - 如果用户只是想在自己机器上单独配置一个**脱离 Anna** 的 ` + "`lark-cli`" + `，那才回退到上游原生的 ` + "`config init`" + ` / ` + "`auth login`" + ` 流程。
 
@@ -285,8 +285,9 @@ name: lark
 description: |
   Lark/Feishu CLI skills for Anna sessions. Covers workspace operations — calendar,
   docs, tasks, mail, and messenger — via the lark-cli tool. In Anna, lark-cli runs
-  under a wrapper + env-var auth model: LARK_ACCESS_TOKEN, LARK_APP_ID, and
-  LARK_BRAND are injected at session start; no manual config init or auth login is
+  under a wrapper + env-var auth model: LARKSUITE_CLI_USER_ACCESS_TOKEN,
+  LARKSUITE_CLI_APP_ID, and LARKSUITE_CLI_BRAND are injected at session start;
+  no manual config init or auth login is
   needed. Always read lark-shared first for identity selection (--as user vs --as
   bot), scope / permission-denied handling, token refresh, and the Anna-specific
   rules that override upstream documentation.
@@ -301,7 +302,7 @@ metadata:
 
 This skill aggregates Lark/Feishu CLI modules synced from ` + "`larksuite/cli`" + ` and adapted for Anna sessions.
 
-**Anna auth model** — ` + "`lark-cli`" + ` runs via a session wrapper that injects ` + "`LARK_ACCESS_TOKEN`" + `, ` + "`LARK_APP_ID`" + `, and ` + "`LARK_BRAND`" + ` at startup. Do not run ` + "`lark-cli config init`" + ` or ` + "`lark-cli auth login`" + ` unless the user explicitly wants a standalone local setup outside Anna.
+**Anna auth model** — ` + "`lark-cli`" + ` runs via a session wrapper that injects ` + "`LARKSUITE_CLI_USER_ACCESS_TOKEN`" + `, ` + "`LARKSUITE_CLI_APP_ID`" + `, and ` + "`LARKSUITE_CLI_BRAND`" + ` at startup. Do not run ` + "`lark-cli config init`" + ` or ` + "`lark-cli auth login`" + ` unless the user explicitly wants a standalone local setup outside Anna.
 
 **Identity** — default to ` + "`--as user`" + ` for personal resources (calendar, docs, tasks, mail). ` + "`--as bot`" + ` requires manual app configuration outside Anna and cannot see user-private resources.
 
diff --git a/internal/oauthcli/token_manager.go b/internal/oauthcli/token_manager.go
index 8c404713..5ee79fb9 100644
--- a/internal/oauthcli/token_manager.go
+++ b/internal/oauthcli/token_manager.go
@@ -44,6 +44,9 @@ func (m *TokenManager) GetGHToken(ctx context.Context, userID int64) (string, er
 // It loads the Lark bundle, refreshes the access token if expired, and returns
 // a map ready for env injection. Returns an error if the bundle is absent or
 // the refresh token has expired, so callers can skip injection without failing.
+//
+// Current lark-cli releases read the LARKSUITE_CLI_* variables for configless
+// runtime auth.
 func (m *TokenManager) GetLarkRuntimeEnv(ctx context.Context, userID int64) (map[string]string, error) {
 	bundle, err := LoadLarkBundle(ctx, m.vs, userID)
 	if err != nil {
@@ -76,9 +79,9 @@ func (m *TokenManager) GetLarkRuntimeEnv(ctx context.Context, userID int64) (map
 	}
 
 	return map[string]string{
-		"LARK_ACCESS_TOKEN": bundle.AccessToken,
-		"LARK_APP_ID":       bundle.AppID,
-		"LARK_BRAND":        bundle.Brand,
+		"LARKSUITE_CLI_USER_ACCESS_TOKEN": bundle.AccessToken,
+		"LARKSUITE_CLI_APP_ID":            bundle.AppID,
+		"LARKSUITE_CLI_BRAND":             bundle.Brand,
 	}, nil
 }
 
diff --git a/internal/oauthcli/token_manager_test.go b/internal/oauthcli/token_manager_test.go
new file mode 100644
index 00000000..b242ae97
--- /dev/null
+++ b/internal/oauthcli/token_manager_test.go
@@ -0,0 +1,44 @@
+package oauthcli
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestGetLarkRuntimeEnv_ExportsCurrentEnvNames(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(7)
+	now := time.Now().UTC().Truncate(time.Second)
+
+	bundle := LarkOAuthBundle{
+		Version:          1,
+		AppID:            "cli_test_app_id",
+		AppSecret:        "cli_test_app_secret",
+		Brand:            "feishu",
+		AccessToken:      "u-test-access-token",
+		RefreshToken:     "u-test-refresh-token",
+		AccessExpiresAt:  now.Add(2 * time.Hour),
+		RefreshExpiresAt: now.Add(30 * 24 * time.Hour),
+	}
+	if err := SaveLarkBundle(ctx, vs, userID, bundle); err != nil {
+		t.Fatalf("SaveLarkBundle: %v", err)
+	}
+
+	env, err := NewTokenManager(vs).GetLarkRuntimeEnv(ctx, userID)
+	if err != nil {
+		t.Fatalf("GetLarkRuntimeEnv: %v", err)
+	}
+
+	checks := map[string]string{
+		"LARKSUITE_CLI_USER_ACCESS_TOKEN": bundle.AccessToken,
+		"LARKSUITE_CLI_APP_ID":            bundle.AppID,
+		"LARKSUITE_CLI_BRAND":             bundle.Brand,
+	}
+	for key, want := range checks {
+		if got := env[key]; got != want {
+			t.Errorf("%s = %q, want %q", key, got, want)
+		}
+	}
+}
diff --git a/plugins/sandbox/local/session.go b/plugins/sandbox/local/session.go
index 126dacf7..1f0f8348 100644
--- a/plugins/sandbox/local/session.go
+++ b/plugins/sandbox/local/session.go
@@ -1,6 +1,7 @@
-// WARNING: commands run directly on the host OS with OS-level hardening only.
-// Hardening layers applied: process-group isolation, rlimits (Linux),
-// Seatbelt sandbox-exec profile (macOS), bwrap/unshare network isolation (Linux).
+// WARNING: commands run directly on the host OS with limited hardening only.
+// Hardening layers applied: process-group isolation on Unix, rlimits on Linux,
+// bwrap/unshare network isolation on Linux. macOS local execution currently runs
+// without additional OS sandboxing.
 // Use the docker backend when full container isolation is required.
 package local
 
diff --git a/plugins/sandbox/local/session_darwin.go b/plugins/sandbox/local/session_darwin.go
index 67f8e12c..a2b5c9d6 100644
--- a/plugins/sandbox/local/session_darwin.go
+++ b/plugins/sandbox/local/session_darwin.go
@@ -5,37 +5,10 @@ package local
 import (
 	"fmt"
 	"os/exec"
-	"strings"
 
 	sandboxpkg "github.com/vaayne/anna/pkg/sandbox"
 )
 
-// seatbeltProfile is the macOS Seatbelt (sandbox-exec) profile template.
-// WORKSPACE_ROOT is replaced with the actual workspace path.
-// NETWORK_RULE is replaced with the appropriate network allow/deny rule.
-//
-// Seatbelt evaluates rules in order; the last matching rule wins.
-// Strategy: allow file-read* for all paths, then deny specific credential paths
-// after the broad allow so the deny takes precedence. The workspace root read
-// allow comes last to re-permit workspace reads even if the workspace is under
-// a denied prefix (e.g. /Users). Write access is limited to workspace and /tmp.
-const seatbeltProfile = `(version 1)
-(deny default)
-(allow process-exec)
-(allow process-fork)
-(allow file-read* (subpath "/"))
-(deny file-read* (subpath "/Users"))
-(deny file-read* (subpath "/home"))
-(allow file-read* (subpath "WORKSPACE_ROOT"))
-(allow file-write* (subpath "WORKSPACE_ROOT"))
-(allow file-write* (subpath "/tmp"))
-(allow file-write* (subpath "/private/tmp"))
-(deny file-write* (subpath "/Users"))
-(deny file-write* (subpath "/home"))
-(allow sysctl-read)
-NETWORK_RULE
-`
-
 // resolveSandboxRoot returns the sandbox-space root and the real host root.
 // On macOS there is no path remapping, so both are always identical.
 func resolveSandboxRoot(policy sandboxpkg.Policy) (sandboxRoot, realRoot string) {
@@ -43,39 +16,18 @@ func resolveSandboxRoot(policy sandboxpkg.Policy) (sandboxRoot, realRoot string)
 	return real, real
 }
 
-// wrapCommand wraps name+args with sandbox-exec using a Seatbelt profile on
-// macOS. If sandbox-exec is not available, an actionable error is returned.
+// wrapCommand is a no-op on macOS.
 //
-//   - sandboxCwd: the working directory in sandbox space (equals real path on macOS).
-//   - hostCwd returned: sandboxCwd (no remapping on macOS).
-func wrapCommand(policy sandboxpkg.Policy, sandboxCwd, name string, args []string) (execPath string, execArgs []string, hostCwd string, err error) {
-	sandboxExecPath, lookErr := exec.LookPath("sandbox-exec")
+// The local backend now runs commands directly on the host OS without applying
+// sandbox-exec or any other macOS-specific isolation layer. Filesystem and
+// network policy enforcement is therefore not provided on this platform when
+// the local backend is active.
+func wrapCommand(_ sandboxpkg.Policy, sandboxCwd, name string, args []string) (execPath string, execArgs []string, hostCwd string, err error) {
+	resolved, lookErr := exec.LookPath(name)
 	if lookErr != nil {
-		return "", nil, "", fmt.Errorf(
-			"local sandbox: sandbox-exec is not available on this macOS version " +
-				"(deprecated since macOS 10.15, may have been removed); " +
-				"use the docker backend for isolation",
-		)
+		return "", nil, "", fmt.Errorf("local exec: look up %q: %w", name, lookErr)
 	}
 
-	workspaceRoot := policy.WorkspaceRootOrDefault()
-	networkMode := policy.NetworkModeOrDefault()
-
-	var networkRule string
-	if networkMode == sandboxpkg.NetworkAllowAll {
-		networkRule = "(allow network*)"
-	} else {
-		networkRule = "(deny network*)"
-	}
-
-	// Escape special characters in the workspace root path for the profile.
-	escapedRoot := strings.ReplaceAll(workspaceRoot, `\`, `\\`)
-	escapedRoot = strings.ReplaceAll(escapedRoot, `"`, `\"`)
-
-	profile := strings.ReplaceAll(seatbeltProfile, "WORKSPACE_ROOT", escapedRoot)
-	profile = strings.ReplaceAll(profile, "NETWORK_RULE", networkRule)
-
-	sandboxArgs := []string{"-p", profile, name}
-	sandboxArgs = append(sandboxArgs, args...)
-	return sandboxExecPath, sandboxArgs, sandboxCwd, nil
+	passthroughArgs := append([]string(nil), args...)
+	return resolved, passthroughArgs, sandboxCwd, nil
 }
diff --git a/plugins/sandbox/local/session_darwin_test.go b/plugins/sandbox/local/session_darwin_test.go
index b3b28808..dc1907dd 100644
--- a/plugins/sandbox/local/session_darwin_test.go
+++ b/plugins/sandbox/local/session_darwin_test.go
@@ -1,95 +1,67 @@
 package local
 
 import (
-	"strings"
+	"os/exec"
+	"reflect"
 	"testing"
 
 	sandboxpkg "github.com/vaayne/anna/pkg/sandbox"
 )
 
-// TestWrapCommand_darwin_containsWorkspaceRoot verifies that the Seatbelt
-// profile generated by wrapCommand contains the workspace root path.
-func TestWrapCommand_darwin_containsWorkspaceRoot(t *testing.T) {
+func TestWrapCommand_darwin_passthrough(t *testing.T) {
 	root := "/tmp/test-workspace"
 	policy := sandboxpkg.Policy{
 		Filesystem: sandboxpkg.FilesystemPolicy{
 			WorkspaceRoot: root,
 			WorkingDir:    root,
 		},
-		Network: sandboxpkg.NetworkPolicy{Mode: sandboxpkg.NetworkAllowAll},
+		Network: sandboxpkg.NetworkPolicy{Mode: sandboxpkg.NetworkDisabled},
 	}
 
-	_, args, _, err := wrapCommand(policy, root, "sh", []string{"-c", "echo hi"})
+	execPath, args, hostCwd, err := wrapCommand(policy, root, "sh", []string{"-c", "echo hi"})
 	if err != nil {
-		// sandbox-exec may not be present on all macOS versions; skip in that case.
-		if strings.Contains(err.Error(), "sandbox-exec unavailable") {
-			t.Skip("sandbox-exec not available on this system")
-		}
 		t.Fatalf("unexpected error: %v", err)
 	}
 
-	// args[0] should be "-p", args[1] should be the profile.
-	if len(args) < 2 || args[0] != "-p" {
-		t.Fatalf("expected args to start with [-p <profile> ...], got %v", args)
+	wantExecPath, err := exec.LookPath("sh")
+	if err != nil {
+		t.Fatalf("look up sh: %v", err)
 	}
-	profile := args[1]
-	if !strings.Contains(profile, root) {
-		t.Errorf("profile does not contain workspace root %q:\n%s", root, profile)
+	if execPath != wantExecPath {
+		t.Fatalf("execPath = %q, want %q", execPath, wantExecPath)
+	}
+	if !reflect.DeepEqual(args, []string{"-c", "echo hi"}) {
+		t.Fatalf("args = %#v, want passthrough args", args)
+	}
+	if hostCwd != root {
+		t.Fatalf("hostCwd = %q, want %q", hostCwd, root)
 	}
 }
 
-// TestWrapCommand_darwin_networkAllow verifies the network allow rule is present.
-func TestWrapCommand_darwin_networkAllow(t *testing.T) {
+func TestWrapCommand_darwin_ignoresNetworkPolicy(t *testing.T) {
 	root := "/tmp/test-workspace"
-	policy := sandboxpkg.Policy{
+	allowAll := sandboxpkg.Policy{
 		Filesystem: sandboxpkg.FilesystemPolicy{
 			WorkspaceRoot: root,
 			WorkingDir:    root,
 		},
 		Network: sandboxpkg.NetworkPolicy{Mode: sandboxpkg.NetworkAllowAll},
 	}
-
-	_, args, _, err := wrapCommand(policy, root, "sh", []string{"-c", "echo hi"})
-	if err != nil {
-		if strings.Contains(err.Error(), "sandbox-exec unavailable") {
-			t.Skip("sandbox-exec not available on this system")
-		}
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	if len(args) < 2 {
-		t.Fatalf("too few args: %v", args)
-	}
-	profile := args[1]
-	if !strings.Contains(profile, "(allow network*)") {
-		t.Errorf("expected '(allow network*)' in profile, got:\n%s", profile)
+	disabled := sandboxpkg.Policy{
+		Filesystem: allowAll.Filesystem,
+		Network:    sandboxpkg.NetworkPolicy{Mode: sandboxpkg.NetworkDisabled},
 	}
-}
 
-// TestWrapCommand_darwin_networkDeny verifies the network deny rule is present.
-func TestWrapCommand_darwin_networkDeny(t *testing.T) {
-	root := "/tmp/test-workspace"
-	policy := sandboxpkg.Policy{
-		Filesystem: sandboxpkg.FilesystemPolicy{
-			WorkspaceRoot: root,
-			WorkingDir:    root,
-		},
-		Network: sandboxpkg.NetworkPolicy{Mode: sandboxpkg.NetworkDisabled},
+	_, allowArgs, _, err := wrapCommand(allowAll, root, "sh", []string{"-c", "echo hi"})
+	if err != nil {
+		t.Fatalf("allow_all wrapCommand error: %v", err)
 	}
-
-	_, args, _, err := wrapCommand(policy, root, "sh", []string{"-c", "echo hi"})
+	_, disabledArgs, _, err := wrapCommand(disabled, root, "sh", []string{"-c", "echo hi"})
 	if err != nil {
-		if strings.Contains(err.Error(), "sandbox-exec unavailable") {
-			t.Skip("sandbox-exec not available on this system")
-		}
-		t.Fatalf("unexpected error: %v", err)
+		t.Fatalf("disabled wrapCommand error: %v", err)
 	}
 
-	if len(args) < 2 {
-		t.Fatalf("too few args: %v", args)
-	}
-	profile := args[1]
-	if !strings.Contains(profile, "(deny network*)") {
-		t.Errorf("expected '(deny network*)' in profile, got:\n%s", profile)
+	if !reflect.DeepEqual(allowArgs, disabledArgs) {
+		t.Fatalf("network policy should not affect darwin local wrapping: allow=%#v disabled=%#v", allowArgs, disabledArgs)
 	}
 }

From 1803b8c55520688e9a7f3c11d5b3aa24fb4184e7 Mon Sep 17 00:00:00 2001
From: Vaayne <vaayne@mbp14.local>
Date: Wed, 22 Apr 2026 15:06:31 +0800
Subject: [PATCH 21/21] =?UTF-8?q?=E2=9C=A8=20test:=20add=20unit=20tests=20?=
 =?UTF-8?q?for=20OAuth=20CLI=20auth=20plugins=20and=20improve=20oauthcli?=
 =?UTF-8?q?=20coverage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add comprehensive tests for plugins/auth/github (94.7% coverage)
- Add comprehensive tests for plugins/auth/lark (95.7% coverage)
- Expand token_manager tests in internal/oauthcli for GetGHToken and error cases

This raises total coverage from 49.5% to 50.1%, meeting the 50% threshold.

Assisted-by: pi:gpt-5.4
---
 internal/oauthcli/token_manager_test.go | 116 ++++++
 plugins/auth/github/plugin_test.go      | 344 +++++++++++++++++
 plugins/auth/lark/plugin_test.go        | 472 ++++++++++++++++++++++++
 3 files changed, 932 insertions(+)
 create mode 100644 plugins/auth/github/plugin_test.go
 create mode 100644 plugins/auth/lark/plugin_test.go

diff --git a/internal/oauthcli/token_manager_test.go b/internal/oauthcli/token_manager_test.go
index b242ae97..5032f59b 100644
--- a/internal/oauthcli/token_manager_test.go
+++ b/internal/oauthcli/token_manager_test.go
@@ -2,10 +2,82 @@ package oauthcli
 
 import (
 	"context"
+	"strings"
 	"testing"
 	"time"
 )
 
+func TestNewTokenManager(t *testing.T) {
+	vs := newMockVaultStore()
+	tm := NewTokenManager(vs)
+	if tm == nil {
+		t.Fatal("NewTokenManager() returned nil")
+	}
+	if tm.vs != vs {
+		t.Error("NewTokenManager() did not store vault store correctly")
+	}
+}
+
+func TestGetGHToken_Success(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(1)
+
+	bundle := GHOAuthBundle{
+		Version:     1,
+		AccessToken: "ghp_test_token_12345",
+		TokenType:   "bearer",
+	}
+	if err := SaveGHBundle(ctx, vs, userID, bundle); err != nil {
+		t.Fatalf("SaveGHBundle: %v", err)
+	}
+
+	token, err := NewTokenManager(vs).GetGHToken(ctx, userID)
+	if err != nil {
+		t.Fatalf("GetGHToken: %v", err)
+	}
+	if token != bundle.AccessToken {
+		t.Errorf("GetGHToken = %q, want %q", token, bundle.AccessToken)
+	}
+}
+
+func TestGetGHToken_NoBundle(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(42)
+
+	_, err := NewTokenManager(vs).GetGHToken(ctx, userID)
+	if err == nil {
+		t.Fatal("GetGHToken expected error for missing bundle")
+	}
+	if !strings.Contains(err.Error(), "has not connected GitHub") {
+		t.Errorf("error = %q, expected to contain 'has not connected GitHub'", err.Error())
+	}
+}
+
+func TestGetGHToken_EmptyToken(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(1)
+
+	bundle := GHOAuthBundle{
+		Version:     1,
+		AccessToken: "",
+		TokenType:   "bearer",
+	}
+	if err := SaveGHBundle(ctx, vs, userID, bundle); err != nil {
+		t.Fatalf("SaveGHBundle: %v", err)
+	}
+
+	_, err := NewTokenManager(vs).GetGHToken(ctx, userID)
+	if err == nil {
+		t.Fatal("GetGHToken expected error for empty token")
+	}
+	if !strings.Contains(err.Error(), "empty access token") {
+		t.Errorf("error = %q, expected to contain 'empty access token'", err.Error())
+	}
+}
+
 func TestGetLarkRuntimeEnv_ExportsCurrentEnvNames(t *testing.T) {
 	vs := newMockVaultStore()
 	ctx := context.Background()
@@ -42,3 +114,47 @@ func TestGetLarkRuntimeEnv_ExportsCurrentEnvNames(t *testing.T) {
 		}
 	}
 }
+
+func TestGetLarkRuntimeEnv_NoBundle(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(99)
+
+	_, err := NewTokenManager(vs).GetLarkRuntimeEnv(ctx, userID)
+	if err == nil {
+		t.Fatal("GetLarkRuntimeEnv expected error for missing bundle")
+	}
+	if !strings.Contains(err.Error(), "has not connected Lark/Feishu") {
+		t.Errorf("error = %q, expected to contain 'has not connected Lark/Feishu'", err.Error())
+	}
+}
+
+func TestGetLarkRuntimeEnv_RefreshTokenExpired(t *testing.T) {
+	vs := newMockVaultStore()
+	ctx := context.Background()
+	userID := int64(3)
+	now := time.Now().UTC().Truncate(time.Second)
+
+	// Refresh token already expired
+	bundle := LarkOAuthBundle{
+		Version:          1,
+		AppID:            "test_app_id",
+		AppSecret:        "test_app_secret",
+		Brand:            "lark",
+		AccessToken:      "access-token",
+		RefreshToken:     "refresh-token",
+		AccessExpiresAt:  now.Add(-1 * time.Hour),  // Expired
+		RefreshExpiresAt: now.Add(-1 * time.Hour), // Also expired
+	}
+	if err := SaveLarkBundle(ctx, vs, userID, bundle); err != nil {
+		t.Fatalf("SaveLarkBundle: %v", err)
+	}
+
+	_, err := NewTokenManager(vs).GetLarkRuntimeEnv(ctx, userID)
+	if err == nil {
+		t.Fatal("GetLarkRuntimeEnv expected error for expired refresh token")
+	}
+	if !strings.Contains(err.Error(), "refresh token expired") {
+		t.Errorf("error = %q, expected to contain 'refresh token expired'", err.Error())
+	}
+}
diff --git a/plugins/auth/github/plugin_test.go b/plugins/auth/github/plugin_test.go
new file mode 100644
index 00000000..e0112889
--- /dev/null
+++ b/plugins/auth/github/plugin_test.go
@@ -0,0 +1,344 @@
+package github
+
+import (
+	"testing"
+)
+
+func TestDefaultConfig(t *testing.T) {
+	cfg := defaultConfig()
+	if cfg == nil {
+		t.Fatal("defaultConfig() returned nil")
+	}
+
+	expected := map[string]string{
+		"client_id":     "",
+		"client_secret": "",
+		"redirect_url":  "",
+	}
+
+	for key, want := range expected {
+		if got, ok := cfg[key]; !ok {
+			t.Errorf("defaultConfig() missing key %q", key)
+		} else if got != want {
+			t.Errorf("defaultConfig()[%q] = %v, want %v", key, got, want)
+		}
+	}
+}
+
+func TestConfigSchema(t *testing.T) {
+	schema := configSchema()
+	if schema == nil {
+		t.Fatal("configSchema() returned nil")
+	}
+
+	// Check type
+	if typ, ok := schema["type"].(string); !ok || typ != "object" {
+		t.Errorf("schema[type] = %v, want 'object'", schema["type"])
+	}
+
+	// Check required fields
+	required, ok := schema["required"].([]any)
+	if !ok {
+		t.Fatal("schema[required] not found or wrong type")
+	}
+	if len(required) != 2 {
+		t.Errorf("len(required) = %d, want 2", len(required))
+	}
+
+	// Check properties exist
+	properties, ok := schema["properties"].(map[string]any)
+	if !ok {
+		t.Fatal("schema[properties] not found or wrong type")
+	}
+
+	expectedProps := []string{"client_id", "client_secret", "redirect_url"}
+	for _, prop := range expectedProps {
+		if _, ok := properties[prop]; !ok {
+			t.Errorf("schema missing property %q", prop)
+		}
+	}
+}
+
+func TestDecodeConfig_Valid(t *testing.T) {
+	raw := map[string]any{
+		"client_id":     "test-client-id",
+		"client_secret": "test-secret",
+		"redirect_url":  "https://example.com/callback",
+	}
+
+	cfg, err := decodeConfig(raw)
+	if err != nil {
+		t.Fatalf("decodeConfig() error = %v", err)
+	}
+
+	if cfg.ClientID != "test-client-id" {
+		t.Errorf("ClientID = %q, want %q", cfg.ClientID, "test-client-id")
+	}
+	if cfg.ClientSecret != "test-secret" {
+		t.Errorf("ClientSecret = %q, want %q", cfg.ClientSecret, "test-secret")
+	}
+	if cfg.RedirectURL != "https://example.com/callback" {
+		t.Errorf("RedirectURL = %q, want %q", cfg.RedirectURL, "https://example.com/callback")
+	}
+}
+
+func TestDecodeConfig_Empty(t *testing.T) {
+	raw := map[string]any{}
+
+	cfg, err := decodeConfig(raw)
+	if err != nil {
+		t.Fatalf("decodeConfig() error = %v", err)
+	}
+
+	if cfg.ClientID != "" || cfg.ClientSecret != "" || cfg.RedirectURL != "" {
+		t.Error("decodeConfig() with empty map should return empty config")
+	}
+}
+
+func TestDecodeConfig_InvalidTypes(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  map[string]any
+		want string
+	}{
+		{
+			name: "client_id not string",
+			raw:  map[string]any{"client_id": 123},
+			want: "client_id",
+		},
+		{
+			name: "client_secret not string",
+			raw:  map[string]any{"client_secret": true},
+			want: "client_secret",
+		},
+		{
+			name: "redirect_url not string",
+			raw:  map[string]any{"redirect_url": []string{}},
+			want: "redirect_url",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := decodeConfig(tt.raw)
+			if err == nil {
+				t.Fatal("decodeConfig() expected error")
+			}
+			if err.Error() != tt.want+": must be a string" {
+				t.Errorf("error = %q, want %q", err.Error(), tt.want+": must be a string")
+			}
+		})
+	}
+}
+
+func TestValidateConfig_Valid(t *testing.T) {
+	raw := map[string]any{
+		"client_id":     "test-client-id",
+		"client_secret": "test-secret",
+		"redirect_url":  "https://example.com/callback",
+	}
+
+	if err := validateConfig(raw); err != nil {
+		t.Errorf("validateConfig() error = %v", err)
+	}
+}
+
+func TestValidateConfig_MissingClientID(t *testing.T) {
+	raw := map[string]any{
+		"client_secret": "test-secret",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for missing client_id")
+	}
+	if err.Error() != "client_id: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "client_id: required")
+	}
+}
+
+func TestValidateConfig_MissingClientSecret(t *testing.T) {
+	raw := map[string]any{
+		"client_id": "test-client-id",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for missing client_secret")
+	}
+	if err.Error() != "client_secret: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "client_secret: required")
+	}
+}
+
+func TestValidateConfig_EmptyClientID(t *testing.T) {
+	raw := map[string]any{
+		"client_id":     "",
+		"client_secret": "test-secret",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for empty client_id")
+	}
+	if err.Error() != "client_id: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "client_id: required")
+	}
+}
+
+func TestValidateConfig_EmptyClientSecret(t *testing.T) {
+	raw := map[string]any{
+		"client_id":     "test-client-id",
+		"client_secret": "",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for empty client_secret")
+	}
+	if err.Error() != "client_secret: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "client_secret: required")
+	}
+}
+
+func TestValidateConfig_InvalidDecode(t *testing.T) {
+	raw := map[string]any{
+		"client_id": 123,
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error")
+	}
+	if err.Error() != "client_id: must be a string" {
+		t.Errorf("error = %q, want %q", err.Error(), "client_id: must be a string")
+	}
+}
+
+func TestRedactConfig(t *testing.T) {
+	raw := map[string]any{
+		"client_id":     "test-client-id",
+		"client_secret": "super-secret-value",
+		"redirect_url":  "https://example.com/callback",
+	}
+
+	redacted := redactConfig(raw)
+
+	// Check client_secret is redacted
+	if redacted["client_secret"] != "***" {
+		t.Errorf("redacted[client_secret] = %q, want %q", redacted["client_secret"], "***")
+	}
+
+	// Check other fields are preserved
+	if redacted["client_id"] != "test-client-id" {
+		t.Errorf("redacted[client_id] = %q, want %q", redacted["client_id"], "test-client-id")
+	}
+	if redacted["redirect_url"] != "https://example.com/callback" {
+		t.Errorf("redacted[redirect_url] = %q, want %q", redacted["redirect_url"], "https://example.com/callback")
+	}
+
+	// Check original is not modified
+	if raw["client_secret"] != "super-secret-value" {
+		t.Error("redactConfig() modified the original map")
+	}
+}
+
+func TestRedactConfig_NoSecret(t *testing.T) {
+	raw := map[string]any{
+		"client_id":    "test-client-id",
+		"redirect_url": "https://example.com/callback",
+	}
+
+	redacted := redactConfig(raw)
+
+	// Check fields are preserved
+	if redacted["client_id"] != "test-client-id" {
+		t.Errorf("redacted[client_id] = %q, want %q", redacted["client_id"], "test-client-id")
+	}
+	if redacted["redirect_url"] != "https://example.com/callback" {
+		t.Errorf("redacted[redirect_url] = %q, want %q", redacted["redirect_url"], "https://example.com/callback")
+	}
+}
+
+func TestIsConfigured(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  map[string]any
+		want bool
+	}{
+		{
+			name: "fully configured",
+			raw: map[string]any{
+				"client_id":     "test-client-id",
+				"client_secret": "test-secret",
+			},
+			want: true,
+		},
+		{
+			name: "missing client_id",
+			raw: map[string]any{
+				"client_secret": "test-secret",
+			},
+			want: false,
+		},
+		{
+			name: "missing client_secret",
+			raw: map[string]any{
+				"client_id": "test-client-id",
+			},
+			want: false,
+		},
+		{
+			name: "empty client_id",
+			raw: map[string]any{
+				"client_id":     "",
+				"client_secret": "test-secret",
+			},
+			want: false,
+		},
+		{
+			name: "empty client_secret",
+			raw: map[string]any{
+				"client_id":     "test-client-id",
+				"client_secret": "",
+			},
+			want: false,
+		},
+		{
+			name: "invalid type",
+			raw: map[string]any{
+				"client_id": 123,
+			},
+			want: false,
+		},
+		{
+			name: "empty map",
+			raw:  map[string]any{},
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := isConfigured(tt.raw); got != tt.want {
+				t.Errorf("isConfigured() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestConfigured_Exported(t *testing.T) {
+	raw := map[string]any{
+		"client_id":     "test-client-id",
+		"client_secret": "test-secret",
+	}
+
+	if !Configured(raw) {
+		t.Error("Configured() should return true for valid config")
+	}
+
+	raw["client_id"] = ""
+	if Configured(raw) {
+		t.Error("Configured() should return false when client_id is empty")
+	}
+}
diff --git a/plugins/auth/lark/plugin_test.go b/plugins/auth/lark/plugin_test.go
new file mode 100644
index 00000000..ecfeaf56
--- /dev/null
+++ b/plugins/auth/lark/plugin_test.go
@@ -0,0 +1,472 @@
+package lark
+
+import (
+	"testing"
+)
+
+func TestDefaultConfig(t *testing.T) {
+	cfg := defaultConfig()
+	if cfg == nil {
+		t.Fatal("defaultConfig() returned nil")
+	}
+
+	expected := map[string]string{
+		"app_id":       "",
+		"app_secret":   "",
+		"brand":        "lark",
+		"redirect_url": "",
+	}
+
+	for key, want := range expected {
+		if got, ok := cfg[key]; !ok {
+			t.Errorf("defaultConfig() missing key %q", key)
+		} else if got != want {
+			t.Errorf("defaultConfig()[%q] = %v, want %v", key, got, want)
+		}
+	}
+}
+
+func TestConfigSchema(t *testing.T) {
+	schema := configSchema()
+	if schema == nil {
+		t.Fatal("configSchema() returned nil")
+	}
+
+	// Check type
+	if typ, ok := schema["type"].(string); !ok || typ != "object" {
+		t.Errorf("schema[type] = %v, want 'object'", schema["type"])
+	}
+
+	// Check required fields
+	required, ok := schema["required"].([]any)
+	if !ok {
+		t.Fatal("schema[required] not found or wrong type")
+	}
+	if len(required) != 3 {
+		t.Errorf("len(required) = %d, want 3", len(required))
+	}
+
+	// Check properties exist
+	properties, ok := schema["properties"].(map[string]any)
+	if !ok {
+		t.Fatal("schema[properties] not found or wrong type")
+	}
+
+	expectedProps := []string{"app_id", "app_secret", "brand", "redirect_url"}
+	for _, prop := range expectedProps {
+		if _, ok := properties[prop]; !ok {
+			t.Errorf("schema missing property %q", prop)
+		}
+	}
+
+	// Check brand enum
+	brandProp, ok := properties["brand"].(map[string]any)
+	if !ok {
+		t.Fatal("brand property not found or wrong type")
+	}
+	enum, ok := brandProp["enum"].([]any)
+	if !ok || len(enum) != 2 {
+		t.Errorf("brand[enum] = %v, want 2 items", enum)
+	}
+}
+
+func TestDecodeConfig_Valid(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  map[string]any
+		want Config
+	}{
+		{
+			name: "lark brand",
+			raw: map[string]any{
+				"app_id":       "test-app-id",
+				"app_secret":   "test-secret",
+				"brand":        "lark",
+				"redirect_url": "https://example.com/callback",
+			},
+			want: Config{
+				AppID:       "test-app-id",
+				AppSecret:   "test-secret",
+				Brand:       "lark",
+				RedirectURL: "https://example.com/callback",
+			},
+		},
+		{
+			name: "feishu brand",
+			raw: map[string]any{
+				"app_id":       "test-app-id",
+				"app_secret":   "test-secret",
+				"brand":        "feishu",
+				"redirect_url": "https://example.com/callback",
+			},
+			want: Config{
+				AppID:       "test-app-id",
+				AppSecret:   "test-secret",
+				Brand:       "feishu",
+				RedirectURL: "https://example.com/callback",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg, err := decodeConfig(tt.raw)
+			if err != nil {
+				t.Fatalf("decodeConfig() error = %v", err)
+			}
+			if cfg != tt.want {
+				t.Errorf("decodeConfig() = %+v, want %+v", cfg, tt.want)
+			}
+		})
+	}
+}
+
+func TestDecodeConfig_Empty(t *testing.T) {
+	raw := map[string]any{}
+
+	cfg, err := decodeConfig(raw)
+	if err != nil {
+		t.Fatalf("decodeConfig() error = %v", err)
+	}
+
+	if cfg.AppID != "" || cfg.AppSecret != "" || cfg.Brand != "" || cfg.RedirectURL != "" {
+		t.Error("decodeConfig() with empty map should return empty config")
+	}
+}
+
+func TestDecodeConfig_InvalidTypes(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  map[string]any
+		want string
+	}{
+		{
+			name: "app_id not string",
+			raw:  map[string]any{"app_id": 123},
+			want: "app_id",
+		},
+		{
+			name: "app_secret not string",
+			raw:  map[string]any{"app_secret": true},
+			want: "app_secret",
+		},
+		{
+			name: "brand not string",
+			raw:  map[string]any{"brand": []string{}},
+			want: "brand",
+		},
+		{
+			name: "redirect_url not string",
+			raw:  map[string]any{"redirect_url": 456.78},
+			want: "redirect_url",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := decodeConfig(tt.raw)
+			if err == nil {
+				t.Fatal("decodeConfig() expected error")
+			}
+			if err.Error() != tt.want+": must be a string" {
+				t.Errorf("error = %q, want %q", err.Error(), tt.want+": must be a string")
+			}
+		})
+	}
+}
+
+func TestValidateConfig_Valid(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  map[string]any
+	}{
+		{
+			name: "lark brand",
+			raw: map[string]any{
+				"app_id":     "test-app-id",
+				"app_secret": "test-secret",
+				"brand":      "lark",
+			},
+		},
+		{
+			name: "feishu brand",
+			raw: map[string]any{
+				"app_id":     "test-app-id",
+				"app_secret": "test-secret",
+				"brand":      "feishu",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if err := validateConfig(tt.raw); err != nil {
+				t.Errorf("validateConfig() error = %v", err)
+			}
+		})
+	}
+}
+
+func TestValidateConfig_MissingAppID(t *testing.T) {
+	raw := map[string]any{
+		"app_secret": "test-secret",
+		"brand":      "lark",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for missing app_id")
+	}
+	if err.Error() != "app_id: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "app_id: required")
+	}
+}
+
+func TestValidateConfig_MissingAppSecret(t *testing.T) {
+	raw := map[string]any{
+		"app_id": "test-app-id",
+		"brand":  "lark",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for missing app_secret")
+	}
+	if err.Error() != "app_secret: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "app_secret: required")
+	}
+}
+
+func TestValidateConfig_EmptyAppID(t *testing.T) {
+	raw := map[string]any{
+		"app_id":     "",
+		"app_secret": "test-secret",
+		"brand":      "lark",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for empty app_id")
+	}
+	if err.Error() != "app_id: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "app_id: required")
+	}
+}
+
+func TestValidateConfig_MissingBrand(t *testing.T) {
+	raw := map[string]any{
+		"app_id":     "test-app-id",
+		"app_secret": "test-secret",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for missing brand")
+	}
+	if err.Error() != "brand: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "brand: required")
+	}
+}
+
+func TestValidateConfig_EmptyBrand(t *testing.T) {
+	raw := map[string]any{
+		"app_id":     "test-app-id",
+		"app_secret": "test-secret",
+		"brand":      "",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for empty brand")
+	}
+	if err.Error() != "brand: required" {
+		t.Errorf("error = %q, want %q", err.Error(), "brand: required")
+	}
+}
+
+func TestValidateConfig_InvalidBrand(t *testing.T) {
+	raw := map[string]any{
+		"app_id":     "test-app-id",
+		"app_secret": "test-secret",
+		"brand":      "invalid-brand",
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error for invalid brand")
+	}
+	want := "brand: must be one of \"lark\" or \"feishu\""
+	if err.Error() != want {
+		t.Errorf("error = %q, want %q", err.Error(), want)
+	}
+}
+
+func TestValidateConfig_InvalidDecode(t *testing.T) {
+	raw := map[string]any{
+		"app_id": 123,
+	}
+
+	err := validateConfig(raw)
+	if err == nil {
+		t.Fatal("validateConfig() expected error")
+	}
+	if err.Error() != "app_id: must be a string" {
+		t.Errorf("error = %q, want %q", err.Error(), "app_id: must be a string")
+	}
+}
+
+func TestRedactConfig(t *testing.T) {
+	raw := map[string]any{
+		"app_id":       "test-app-id",
+		"app_secret":   "super-secret-value",
+		"brand":        "lark",
+		"redirect_url": "https://example.com/callback",
+	}
+
+	redacted := redactConfig(raw)
+
+	// Check app_secret is redacted
+	if redacted["app_secret"] != "***" {
+		t.Errorf("redacted[app_secret] = %q, want %q", redacted["app_secret"], "***")
+	}
+
+	// Check other fields are preserved
+	if redacted["app_id"] != "test-app-id" {
+		t.Errorf("redacted[app_id] = %q, want %q", redacted["app_id"], "test-app-id")
+	}
+	if redacted["brand"] != "lark" {
+		t.Errorf("redacted[brand] = %q, want %q", redacted["brand"], "lark")
+	}
+	if redacted["redirect_url"] != "https://example.com/callback" {
+		t.Errorf("redacted[redirect_url] = %q, want %q", redacted["redirect_url"], "https://example.com/callback")
+	}
+
+	// Check original is not modified
+	if raw["app_secret"] != "super-secret-value" {
+		t.Error("redactConfig() modified the original map")
+	}
+}
+
+func TestRedactConfig_NoSecret(t *testing.T) {
+	raw := map[string]any{
+		"app_id":       "test-app-id",
+		"brand":        "feishu",
+		"redirect_url": "https://example.com/callback",
+	}
+
+	redacted := redactConfig(raw)
+
+	// Check fields are preserved
+	if redacted["app_id"] != "test-app-id" {
+		t.Errorf("redacted[app_id] = %q, want %q", redacted["app_id"], "test-app-id")
+	}
+	if redacted["brand"] != "feishu" {
+		t.Errorf("redacted[brand] = %q, want %q", redacted["brand"], "feishu")
+	}
+}
+
+func TestIsConfigured(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  map[string]any
+		want bool
+	}{
+		{
+			name: "fully configured lark",
+			raw: map[string]any{
+				"app_id":     "test-app-id",
+				"app_secret": "test-secret",
+				"brand":      "lark",
+			},
+			want: true,
+		},
+		{
+			name: "fully configured feishu",
+			raw: map[string]any{
+				"app_id":     "test-app-id",
+				"app_secret": "test-secret",
+				"brand":      "feishu",
+			},
+			want: true,
+		},
+		{
+			name: "missing app_id",
+			raw: map[string]any{
+				"app_secret": "test-secret",
+				"brand":      "lark",
+			},
+			want: false,
+		},
+		{
+			name: "missing app_secret",
+			raw: map[string]any{
+				"app_id": "test-app-id",
+				"brand":  "lark",
+			},
+			want: false,
+		},
+		{
+			name: "missing brand",
+			raw: map[string]any{
+				"app_id":     "test-app-id",
+				"app_secret": "test-secret",
+			},
+			want: false,
+		},
+		{
+			name: "empty app_id",
+			raw: map[string]any{
+				"app_id":     "",
+				"app_secret": "test-secret",
+				"brand":      "lark",
+			},
+			want: false,
+		},
+		{
+			name: "empty brand",
+			raw: map[string]any{
+				"app_id":     "test-app-id",
+				"app_secret": "test-secret",
+				"brand":      "",
+			},
+			want: false,
+		},
+		{
+			name: "invalid type",
+			raw: map[string]any{
+				"app_id": 123,
+			},
+			want: false,
+		},
+		{
+			name: "empty map",
+			raw:  map[string]any{},
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := isConfigured(tt.raw); got != tt.want {
+				t.Errorf("isConfigured() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestConfigured_Exported(t *testing.T) {
+	raw := map[string]any{
+		"app_id":     "test-app-id",
+		"app_secret": "test-secret",
+		"brand":      "lark",
+	}
+
+	if !Configured(raw) {
+		t.Error("Configured() should return true for valid config")
+	}
+
+	raw["app_id"] = ""
+	if Configured(raw) {
+		t.Error("Configured() should return false when app_id is empty")
+	}
+}