MailUI4Agents/gateway/internal/repo/permission_mode.go

package repo

// 会话级权限档位的读写。
//
// ## 为什么档位挂在会话上而不是每封邮件上
//
// 与配额同一个理由（见 quota.go 的注释）：档位是**任务**的属性。
// 「这件事只许你看不许你动」描述的是任务性质，不是某一封信的性质。
//
// 如果续谈的邮件也能带档位，每封新信都会悄悄改掉对方正在遵守的规则 ——
// 而 plan 档的会话里模型已经被告知「只许看」，第二封信把它改成 full，
// 是在一段已有上下文里换规则。人不一定意识到自己改了。
//
// 所以：**新建会话时设，续谈时忽略该字段，在对话页里显式编辑。**
//
// ## 为什么 Agent 不能自己指定档位
//
// 否则 Agent 发一封 mode=full 的信就给自己提权了。Agent 派活时子会话的档位
// 由 InheritedMode 从父会话推导，且**只能同档或更严**（models.ModeAtMost）。
// 这保证 plan 档的任务派不出 full 档的子任务 —— 与 hop_limit 一个形状。

import (
	"context"
	"fmt"

	"github.com/agentmail/gateway/internal/db"
	"github.com/agentmail/gateway/internal/models"
	"github.com/google/uuid"
)

// SessionPermission 是一条会话的档位与实际强制力。
//
// 两个字段必须一起返回：档位是「要求什么」，强制力是「平台实际做到了什么」。
// 只给前者会让人以为 plan 档管住了 homeagent（它的核心没有工具调用拦截点）。
type SessionPermission struct {
	Mode        string `json:"permission_mode"`
	Enforcement string `json:"permission_enforcement"`
}

// GetSessionPermission 读一条会话的档位与强制力。
//
// 读出来的值一律过 Normalize：库里可能有历史脏数据（手工改库、旧版本写入），
// 而调用方拿到一个认不出的档位时的行为无法预期。归一化在这里做一次，
// 后续所有判断就都能假定值是合法的。
func GetSessionPermission(ctx context.Context, id uuid.UUID) (SessionPermission, error) {
	var p SessionPermission
	err := db.DB.QueryRowContext(ctx,
		`SELECT COALESCE(NULLIF(permission_mode, ''), 'workspace'),
		        COALESCE(NULLIF(permission_enforcement, ''), 'advisory')
		 FROM sessions WHERE session_id = $1`, id).Scan(&p.Mode, &p.Enforcement)
	if err != nil {
		return SessionPermission{}, err
	}
	p.Mode = models.NormalizePermissionMode(p.Mode)
	p.Enforcement = models.NormalizeEnforcement(p.Enforcement)
	return p, nil
}

// SessionPermissionMode 只取档位，读不到时回落默认档。
//
// 供投递路径使用：那里拿不到档位也得继续走（不能因为查询失败就拒收邮件），
// 但回落必须是默认档而不是 full —— 查询失败不该换来更大的权限。
func SessionPermissionMode(ctx context.Context, id uuid.UUID) string {
	p, err := GetSessionPermission(ctx, id)
	if err != nil {
		return models.DefaultPermissionMode
	}
	return p.Mode
}

// SetSessionPermissionMode 设置会话档位。
//
// 非法档位一律收敛成默认档而不是报错：这个函数的调用方包括人在界面上操作，
// 而界面传来一个拼错的值时，静默用默认档比让整次操作失败更合理 ——
// 默认档本身是安全的。
func SetSessionPermissionMode(ctx context.Context, id uuid.UUID, mode string) (SessionPermission, error) {
	m := models.NormalizePermissionMode(mode)
	tag, err := db.DB.ExecContext(ctx,
		`UPDATE sessions SET permission_mode = $2, updated_at = NOW() WHERE session_id = $1`,
		id, m)
	if err != nil {
		return SessionPermission{}, err
	}
	if n, _ := tag.RowsAffected(); n == 0 {
		return SessionPermission{}, fmt.Errorf("会话 %s 不存在", id)
	}
	return GetSessionPermission(ctx, id)
}

// SetSessionEnforcement 记录接收平台实际做到的强制力。
//
// 由投递路径在建会话时按收件 Agent 的自报能力写入 —— 它是**事实快照**
// 而不是配置：插件升级后能力会变，但已结束的会话不该被改写成「其实当时
// 是被强制的」。所以不跟着 agents.mode_enforcement 走，而是建会话时定死。
func SetSessionEnforcement(ctx context.Context, id uuid.UUID, enforcement string) error {
	e := models.NormalizeEnforcement(enforcement)
	_, err := db.DB.ExecContext(ctx,
		`UPDATE sessions SET permission_enforcement = $2 WHERE session_id = $1`, id, e)
	return err
}

// AgentModeEnforcement 取某个 Agent 自报的档位强制力。
//
// Agent 不存在或没自报过时返回 advisory：不能替一个没说过话的插件宣称
// 「档位在它那里是被强制的」。保守方向是承认做不到。
func AgentModeEnforcement(ctx context.Context, agentName string) string {
	var e string
	err := db.DB.QueryRowContext(ctx,
		`SELECT COALESCE(NULLIF(mode_enforcement, ''), 'advisory')
		 FROM agents WHERE agent_name = $1`, agentName).Scan(&e)
	if err != nil {
		return models.EnforcementAdvisory
	}
	return models.NormalizeEnforcement(e)
}

// SetAgentModeEnforcement 落库 Agent 心跳自报的档位强制力。
//
// 走心跳而不是注册：注册只在插件启动时发生一次，而能力可能因为配置变化
// （比如 DSH 的 sandbox 被换成 danger-full-access）而改变。与模型目录上报
// 同一条通道 —— I-1：平台自己说的才算。
func SetAgentModeEnforcement(ctx context.Context, agentName, enforcement string) error {
	e := models.NormalizeEnforcement(enforcement)
	_, err := db.DB.ExecContext(ctx,
		`UPDATE agents SET mode_enforcement = $2 WHERE agent_name = $1`, agentName, e)
	return err
}

// InheritedMode 推导子会话应当继承的档位。
//
// parentSessionID 为 nil（人直接发起、或没有父会话可依据）时返回 requested
// 归一化后的值；有父会话时取**父档位与请求档位里更严的那一个**。
//
// 为什么必须取更严：Agent 派活时若能给子会话一个更宽松的档位，plan 档的
// 任务就能通过「派给自己一条 full 档子会话」来提权，档位形同虚设。
// 这与 hop_limit 防自激的形状一样 —— 约束必须沿着链条传递下去。
func InheritedMode(ctx context.Context, parentSessionID *uuid.UUID, requested string) string {
	req := models.NormalizePermissionMode(requested)
	if parentSessionID == nil {
		return req
	}
	parent, err := GetSessionPermission(ctx, *parentSessionID)
	if err != nil {
		// 父会话查不到时按默认档与请求档取更严 —— 不能因为查询失败而放宽。
		return models.ModeAtMost(models.DefaultPermissionMode, req)
	}
	return models.ModeAtMost(parent.Mode, req)
}