diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a0dd92cba..22f08c0451 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ ## [1.0.3b7] - 2026-11-17 ### 新增 +- 专家记忆新增 MCP Server(`/mcp/memory`):外部 Agent / Bot 用用户级 token 检索、写入、采集专家记忆;token 可按客户端命名、限定专家范围并单独吊销,外部写入默认进入审核队列;并提供 Claude Code / Kiro / DSH / Codex / Cursor 一键接入(DSH 走原生插件,支持项目级安装与 Windows PowerShell);MCP token 直接绑定上报专家、可在面板切换,客户端只带 token 即可 +- 工作台「云服务器」页的地域筛选器改为控制台风格下拉面板:按大区分组展示各地域并标注节点数量,只有有节点的地域才显示红点,同时记住最近访问的地域 - 托管专家可选会话模式,并能使用连接器、知识库、专家回调和已启用的插件 - 云服务器页的地域筛选改为按大区分组的下拉面板 @@ -26,6 +28,8 @@ ## [1.0.3b6] - 2026-11-15 ### 新增 +- 专家市场默认打开「精选」,用书签标出接入市场前随安装包提供的 22 个专家模板 +- 通道卡片与 `/api/health` 展示每个通道的入站、出站、重连和丢弃计数;记忆存储页显示 checkpoint 保留窗口与 VACUUM 提示 - 支持 Helm 集群部署。多实例共用一个 PostgreSQL - 管理员可以限制创建专家时能选的存储后端 - 新增托管专家,对话可以交给后端 Agent,如 OpenCode diff --git a/dashboard/src/api/modules/memoryMcp.ts b/dashboard/src/api/modules/memoryMcp.ts new file mode 100644 index 0000000000..47978c6865 --- /dev/null +++ b/dashboard/src/api/modules/memoryMcp.ts @@ -0,0 +1,132 @@ +/** + * memoryMcp — user-level API tokens for the memory MCP server. + * + * Routes live under ``/api/memory-mcp/tokens`` (``octop.api.routers.memory_mcp``). + * Tokens are personal: a caller acts as the user the token was issued to, so + * ``X-Octop-User-Id`` is never trusted. Only the digest is stored server-side; + * the plaintext value is returned exactly once, at creation. + * + * Wire shapes are snake_case on purpose, mirroring the backend ``TokenOut`` / + * ``TokenCreated`` models. + */ + +import { request } from "../request"; + +/** + * Usage of one client integration, keyed in ``MemoryMcpToken.client_stats`` by + * the ``X-Octop-Client`` value the client sends (e.g. ``claude-code``). + */ +export interface MemoryMcpClientStat { + /** ISO-8601 UTC of the first request carrying this client header. */ + first_seen: string; + /** ISO-8601 UTC of the most recent such request. */ + last_seen: string; + /** Requests seen with this client header. */ + count: number; +} + +export interface MemoryMcpToken { + /** Public id used to revoke the token. */ + token_id: string; + /** Client name supplied at creation, e.g. ``codex@macbook``. */ + name: string; + /** Expert (agent) allow-list; null means every expert the user can access. */ + expert_ids: string[] | null; + /** Masked value safe to display, e.g. ``omcp_…abcd``. */ + token_hint: string; + /** ISO-8601 UTC. */ + created_at: string; + /** ISO-8601 UTC, or null when the token has never been used. */ + last_used_at: string | null; + /** ISO-8601 UTC once revoked; null while the token is active. */ + revoked_at: string | null; + /** + * Clients switched off for this token; null means every client may call. + * A disabled client is rejected server-side regardless of ``client_stats``. + */ + disabled_clients: string[] | null; + /** + * Per-client usage, or null until some client sends ``X-Octop-Client``. + * Requests without that header are counted only in ``last_used_at``. + */ + client_stats: Record | null; +} + +/** Successful create result: the token row plus its one-time plaintext. */ +export interface MemoryMcpTokenCreated { + token: MemoryMcpToken; + plaintext: string; +} + +export interface CreateMemoryMcpTokenBody { + name: string; + /** Omit / null to allow every expert the issuing user can access. */ + expert_ids: string[] | null; +} + +/** + * Partial update body for ``PATCH /memory-mcp/tokens/{token_id}``. + * + * A token bound to exactly one expert needs no ``X-Octop-Agent-Id`` on MCP + * requests (the binding decides where reports land); ``expert_ids: null`` + * clears the binding, which brings the header requirement back. + */ +export interface UpdateMemoryMcpTokenBody { + /** New display name; omitted leaves it untouched. */ + name?: string; + /** Exactly one id pins the expert; null means "no restriction". */ + expert_ids?: string[] | null; + /** Clients switched off; an empty list is sent as null ("all allowed"). */ + disabled_clients?: string[] | null; +} + +export interface RevokeMemoryMcpTokenResponse { + revoked: boolean; +} + +/** Backend ``TokenCreated``: a flat ``TokenOut`` plus the one-time plaintext. */ +type TokenCreatedWire = MemoryMcpToken & { token: string }; + +function toCreated(raw: TokenCreatedWire): MemoryMcpTokenCreated { + const { token, ...row } = raw; + return { token: row, plaintext: token }; +} + +export const memoryMcpApi = { + list: () => request("/memory-mcp/tokens"), + + create: (body: CreateMemoryMcpTokenBody) => + request("/memory-mcp/tokens", { + method: "POST", + body: JSON.stringify(body), + }).then(toCreated), + + /** Rename and/or re-bind the token's expert. Returns ``TokenOut`` (no plaintext). */ + update: (tokenId: string, body: UpdateMemoryMcpTokenBody) => + request( + `/memory-mcp/tokens/${encodeURIComponent(tokenId)}`, + { + method: "PATCH", + body: JSON.stringify(body), + }, + ), + + revoke: (tokenId: string) => + request( + `/memory-mcp/tokens/${encodeURIComponent(tokenId)}`, + { method: "DELETE" }, + ), + + /** + * Issue a fresh secret for an existing token; the old plaintext stops working + * immediately. Returns ``TokenOut`` plus the one-time plaintext, exactly like + * ``create``. Revoked tokens are rejected by the server (409). + */ + rotate: (tokenId: string) => + request( + `/memory-mcp/tokens/${encodeURIComponent(tokenId)}/rotate`, + { method: "POST" }, + ).then(toCreated), +}; + +export default memoryMcpApi; diff --git a/dashboard/src/layouts/sidebarNav.tsx b/dashboard/src/layouts/sidebarNav.tsx index 1cbc4f7460..981dc78f99 100644 --- a/dashboard/src/layouts/sidebarNav.tsx +++ b/dashboard/src/layouts/sidebarNav.tsx @@ -19,6 +19,7 @@ import { GraduationCap, Shield, PanelsTopLeft, + KeyRound, } from "lucide-react"; import type { OctopUser } from "../api/modules/auth"; import { navAllowed, userCan } from "../utils/permissions"; @@ -69,6 +70,7 @@ export const SIDEBAR_NAV_KEYS = [ "experts", "tasks", "token-usage", + "tokens", "personalization", "channels", "connectors", @@ -123,6 +125,7 @@ export function navSectionLabel( * comes from {@link buildNavSections}. */ export const SIDEBAR_GROUPED_NAV_KEYS = [ + "tokens", "personalization", "channels", "connectors", @@ -234,6 +237,14 @@ export function buildNavSections( labelKey: "nav.bridge", }); } + if (navAllowed(user, "tokens")) { + settingsItems.push({ + key: "tokens", + path: "/tokens", + icon: , + labelKey: "nav.tokens", + }); + } if (settingsItems.length > 0) { sections.push({ id: "settings", diff --git a/dashboard/src/locales/en.json b/dashboard/src/locales/en.json index 7346f3dbc1..b614e93bfd 100644 --- a/dashboard/src/locales/en.json +++ b/dashboard/src/locales/en.json @@ -276,6 +276,7 @@ "WEBAUTHN_LOGIN_DISABLED": "Passkey sign-in on the login page is turned off. An administrator can enable it under App settings → Passkeys." }, "nav": { + "tokens": "Terminal access", "chat": "Conversation", "common": "Common", "control": "Control", @@ -953,10 +954,8 @@ "emptyHint": "No user-published templates yet. On My Experts, click the upload icon on a card to publish one.", "by": "by {{name}}", "install": "Install", - "installTitle": "Install \"{{name}}\"", "installFailed": "Failed to install template", "drawerTitle": "Publish expert template", - "drawerHint": "Only expert config markdown (SOUL, IDENTITY, …), skills, and sub-agent definitions are included. Runtime data such as memory DB, uploads, and built-in skills is excluded.", "fieldName": "Template name", "fieldDescription": "Description", "fieldWelcomeZh": "Welcome message (Chinese)", @@ -4007,7 +4006,6 @@ "emptyGuideStepHowDetail": "Click Add connection and enter the peer address, username, and password. Probe first to confirm the account, then save and connect. Start the link from the side that can reach the other.", "emptyGuideStepChat": "How to chat", "emptyGuideStepChatDetail": "After it connects, remote experts and teams show up under Cloud in the chat sidebar. The Experts tab also lists remote experts, and the Teams tab lists remote teams.", - "drawerHint": "The display name is used for chat group switching and must be unique. Probe first to verify the account; Save & connect only persists after login and the cloud-collab handshake succeed — a failure will not keep the name.", "directionHint": "Initiate from the side that can reach the other. Typically a LAN or laptop connects out to a public/cloud Octop. Probe only checks the account; the handshake must also succeed before the row is saved.", "sectionIdentity": "Display", "sectionRemote": "Peer account", @@ -4785,7 +4783,82 @@ "journal": "Activity", "proactive": "Proactive care", "settings": "Settings", - "userFile": "User profile" + "userFile": "User profile", + "mcp": "Terminal access" + }, + "mcp": { + "title": "Terminal access", + "description": "External agents (Claude Code / Codex / Cursor / Kiro / DSH) use a token here to reach {{endpoint}}. A token is shown only once; create a new one if it is lost.", + "installTitle": "Client setup", + "installWithToken": "Or run this to configure the client right away:", + "copyToken": "Copy token", + "copyCommand": "Copy command", + "tokenLabel": "Token", + "installScriptLabel": "One-line install with hooks (macOS / Linux):", + "installScriptPsLabel": "Windows PowerShell:", + "commandReady": "Copy and keep the token first (it cannot be viewed again after closing). Pick one way to connect below:", + "unboundHint": "This token is not bound to exactly one expert: install scripts cannot work; use this manual config and replace .", + "create": "Create token", + "loadFailed": "Could not load tokens.", + "empty": "No MCP tokens yet", + "emptyHint": "Create one to let an external agent access your memory.", + "columnName": "Name", + "columnHint": "Token hint", + "columnExperts": "Reporting expert", + "columnClients": "Clients", + "columnCreatedAt": "Created", + "columnLastUsedAt": "Last used", + "columnStatus": "Status", + "columnActions": "Actions", + "clientColumnName": "Client", + "clientColumnLastSeen": "Last used", + "clientColumnEnabled": "Enabled", + "clientColumnCount": "Calls", + "clientsEmpty": "No client activity yet (a client shows up after it sends X-Octop-Client).", + "clientSwitchLabel": "{{client}} access", + "clientsUpdated": "Client access updated", + "clientsUpdateFailed": "Could not update client access. Please retry.", + "docsLink": "Setup guide", + "command": "Setup command", + "commandTitle": "Regenerate the setup command", + "commandMissingWarning": "The token plaintext is shown only once, at creation, so the config cannot be rebuilt now. Regenerating invalidates the current token immediately — update every configured client.", + "commandRegenerate": "Regenerate and copy", + "commandRotated": "Regenerated: the old token no longer works. Copy the new config now and update the configured clients.", + "rotateFailed": "Could not regenerate the token. Please retry.", + "allExperts": "Any expert", + "expertCount": "{{count}} expert(s)", + "neverUsed": "Never used", + "statusActive": "Active", + "statusRevoked": "Revoked", + "revoke": "Revoke", + "revokeConfirmTitle": "Revoke this token?", + "revokeConfirmDesc": "External agents using this token lose access to memory immediately. This cannot be undone.", + "revoked": "Token revoked", + "revokeFailed": "Could not revoke the token. Please retry.", + "createTitle": "Create MCP token", + "nameLabel": "Name", + "namePlaceholder": "e.g. codex@macbook", + "nameRequired": "Please enter a name", + "nameTooLong": "Name must be at most 64 characters", + "expertsLabel": "Reporting expert", + "expertsPlaceholder": "Select an expert", + "expertsHint": "The token is bound to this expert: memory reported through it lands here.", + "expertRequired": "Please select an expert", + "expertUnrestricted": "No expert restriction (client must send X-Octop-Agent-Id)", + "switchExpert": "Switch expert", + "switchExpertTitle": "Switch reporting expert", + "switchExpertHint": "New reports through this token land on the new expert. Memory already stored is not migrated.", + "switchExpertPlaceholder": "Select an expert", + "switchExpertSuccess": "Reporting expert updated", + "switchExpertFailed": "Could not switch the expert. Please retry.", + "submit": "Create", + "createFailed": "Could not create the token. Please retry.", + "plaintextTitle": "Token created", + "plaintextWarning": "Copy and save it now. This token is shown only once and cannot be viewed again after closing.", + "copy": "Copy", + "copied": "Copied", + "copyFailed": "Copy failed. Select and copy it manually.", + "close": "Saved, close" }, "strong": { "contextNotice": "Strong memory is loaded once when a session starts and stays in that session's context.", diff --git a/dashboard/src/locales/zh.json b/dashboard/src/locales/zh.json index d003cf6df2..c4e7e0b905 100644 --- a/dashboard/src/locales/zh.json +++ b/dashboard/src/locales/zh.json @@ -276,6 +276,7 @@ "WEBAUTHN_LOGIN_DISABLED": "登录页的通行密钥登录已关闭。管理员可在「应用设置 → 通行密钥」中开启。" }, "nav": { + "tokens": "终端接入", "chat": "对话", "common": "常用", "control": "控制", @@ -953,10 +954,8 @@ "emptyHint": "还没有用户发布的模板。在「我的专家」卡片上点击上传图标即可发布。", "by": "来自 {{name}}", "install": "安装", - "installTitle": "安装「{{name}}」", "installFailed": "安装模板失败", "drawerTitle": "发布专家模板", - "drawerHint": "仅打包专家配置 Markdown(SOUL / IDENTITY 等)、Skills 与子专家定义;对话记忆、上传文件、内置 Skills 等运行时数据不会包含。", "fieldName": "模板名称", "fieldDescription": "模板描述", "fieldWelcomeZh": "中文引导语", @@ -4007,7 +4006,6 @@ "emptyGuideStepHowDetail": "点击「添加连接」,填写对端地址、账号和密码。建议先「探测」确认账号可用,再保存并连接。请从能访问到对端的一侧发起。", "emptyGuideStepChat": "怎么聊天", "emptyGuideStepChatDetail": "连接成功后,对端专家和团队会出现在聊天页的「云端」里。专家页签也会带上云端专家,团队页签会带上云端团队。", - "drawerHint": "显示名用于聊天页分组切换(须唯一)。建议先「探测」确认账号可达;「保存并连接」仅在登录与云端协同握手都成功后才会落库,失败不会占用显示名。", "directionHint": "请从能访问到对端的一侧发起。通常由内网或本机去连公网/云端。探测成功只说明账号可用,还需要握手成功才会保存。", "sectionIdentity": "显示信息", "sectionRemote": "对端账号", @@ -4785,7 +4783,82 @@ "journal": "整理记录", "proactive": "主动关心", "settings": "设置", - "userFile": "用户档案" + "userFile": "用户档案", + "mcp": "终端接入" + }, + "mcp": { + "title": "终端接入", + "description": "外部 Agent(Claude Code / Codex / Cursor / Kiro / DSH)使用这里的 Token 访问 {{endpoint}}。Token 只显示一次,丢失后请重建。", + "installTitle": "客户端配置", + "installWithToken": "也可以直接在终端执行这条命令完成配置:", + "copyToken": "复制 Token", + "copyCommand": "复制命令", + "tokenLabel": "Token", + "installScriptLabel": "一键安装(含 hooks,macOS / Linux):", + "installScriptPsLabel": "Windows PowerShell:", + "commandReady": "请先复制并保存上面的 Token(关闭后无法再次查看)。接入时任选一种方式:", + "unboundHint": "该 Token 未绑定唯一专家:安装脚本不可用,请用此手动配置并把 <专家 ID> 换成要访问的专家。", + "create": "创建 Token", + "loadFailed": "Token 列表加载失败", + "empty": "还没有 MCP Token", + "emptyHint": "创建后即可在外部 Agent 中接入你的记忆。", + "columnName": "名称", + "columnHint": "Token 提示", + "columnExperts": "上报专家", + "columnClients": "接入端", + "columnCreatedAt": "创建时间", + "columnLastUsedAt": "最近使用", + "columnStatus": "状态", + "columnActions": "操作", + "clientColumnName": "客户端", + "clientColumnLastSeen": "最近使用", + "clientColumnEnabled": "启用", + "clientColumnCount": "次数", + "clientsEmpty": "还没有接入记录(客户端带上 X-Octop-Client 后才会出现)", + "clientSwitchLabel": "{{client}} 接入", + "clientsUpdated": "已更新接入端设置", + "clientsUpdateFailed": "更新接入端设置失败,请重试", + "docsLink": "接入说明", + "command": "接入配置", + "commandTitle": "重新生成接入命令", + "commandMissingWarning": "Token 明文只在创建时显示一次,当前无法还原配置。重新生成会立即作废旧 Token,需要同步更新已配置的客户端。", + "commandRegenerate": "重新生成并复制", + "commandRotated": "已重新生成,旧 Token 已失效。请复制新配置并更新已配置的客户端。", + "rotateFailed": "重新生成失败,请重试", + "allExperts": "不限", + "expertCount": "{{count}} 个专家", + "neverUsed": "从未使用", + "statusActive": "有效", + "statusRevoked": "已撤销", + "revoke": "撤销", + "revokeConfirmTitle": "撤销这个 Token?", + "revokeConfirmDesc": "撤销后,使用该 Token 的外部 Agent 将立即无法访问记忆,且不可恢复。", + "revoked": "Token 已撤销", + "revokeFailed": "撤销失败,请重试", + "createTitle": "创建 MCP Token", + "nameLabel": "名称", + "namePlaceholder": "例如 codex@macbook", + "nameRequired": "请填写名称", + "nameTooLong": "名称最多 64 个字符", + "expertsLabel": "上报专家", + "expertsPlaceholder": "请选择上报专家", + "expertsHint": "Token 绑定哪个专家,通过它上报的记忆就落到哪个专家。", + "expertRequired": "请选择上报专家", + "expertUnrestricted": "不限定专家(需客户端带 X-Octop-Agent-Id)", + "switchExpert": "切换专家", + "switchExpertTitle": "切换上报专家", + "switchExpertHint": "切换后,用该 Token 上报的记忆将落到新的专家;已写入的记忆不会迁移。", + "switchExpertPlaceholder": "请选择专家", + "switchExpertSuccess": "已切换上报专家", + "switchExpertFailed": "切换失败,请重试", + "submit": "创建", + "createFailed": "创建失败,请重试", + "plaintextTitle": "Token 已创建", + "plaintextWarning": "请立即复制并妥善保存。此 Token 只显示这一次,关闭后无法再次查看。", + "copy": "复制", + "copied": "已复制", + "copyFailed": "复制失败,请手动选中后复制", + "close": "我已保存,关闭" }, "strong": { "contextNotice": "每个会话开始时加载一次强记忆,并持续用于该会话上下文。", diff --git a/dashboard/src/pages/Agent/Memory/McpAccess.test.tsx b/dashboard/src/pages/Agent/Memory/McpAccess.test.tsx new file mode 100644 index 0000000000..f8c5f01da8 --- /dev/null +++ b/dashboard/src/pages/Agent/Memory/McpAccess.test.tsx @@ -0,0 +1,437 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; +import { render, screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; + +vi.mock("../../../api/modules/memoryMcp", () => ({ + memoryMcpApi: { + list: vi.fn(), + create: vi.fn(), + update: vi.fn(), + revoke: vi.fn(), + rotate: vi.fn(), + }, +})); + +vi.mock("../../../utils/antdMessage", () => ({ + message: { success: vi.fn(), error: vi.fn() }, +})); + +vi.mock("../../../hooks/useServerTimezone", () => ({ + useServerTimezone: () => "Asia/Shanghai", +})); + +vi.mock("../../../utils/copyText", () => ({ + copyText: vi.fn().mockResolvedValue(true), +})); + +// Token expert ids are agent ids, so the page reads the agent list. Two local +// experts are enough to exercise the single-select and the default binding. +vi.mock("../../../context/AgentContext", () => { + const agents = [ + { agent_id: "agent_a", name: "专家甲", bridge: false }, + { agent_id: "agent_b", name: "专家乙", bridge: false }, + ]; + return { + useAgent: () => ({ + agents, + activeAgentId: "agent_b", + activeAgent: null, + loading: false, + error: null, + setActiveAgent: () => undefined, + refresh: async () => undefined, + }), + }; +}); + +import { + memoryMcpApi, + type MemoryMcpToken, +} from "../../../api/modules/memoryMcp"; +import { message } from "../../../utils/antdMessage"; +import { copyText } from "../../../utils/copyText"; +import { formatServerIsoDateTime } from "../../../utils/formatMessageTime"; +import McpAccess from "./McpAccess"; + +const api = vi.mocked(memoryMcpApi, true); +const copyMock = vi.mocked(copyText); + +/** The MCP client config a row copies (expert header for unbound tokens). */ +function clientConfig( + plaintext: string, + expertIds: string[] | null = null, +): string { + const headers: Record = { + Authorization: `Bearer ${plaintext}`, + }; + if (!expertIds || expertIds.length !== 1) { + headers["X-Octop-Agent-Id"] = "<专家 ID>"; + } + return JSON.stringify( + { + mcpServers: { + "octop-memory": { + type: "http", + url: `${window.location.origin}/mcp/memory/`, + headers, + }, + }, + }, + null, + 2, + ); +} + +const activeToken: MemoryMcpToken = { + token_id: "tok_1", + name: "codex@macbook", + expert_ids: null, + token_hint: "omcp_…abcd", + created_at: "2026-11-09T08:00:00Z", + last_used_at: null, + revoked_at: null, + disabled_clients: null, + client_stats: null, +}; + +/** Two clients reported through ``X-Octop-Client``; both currently allowed. */ +const clientToken: MemoryMcpToken = { + ...activeToken, + token_id: "tok_clients", + name: "claude@laptop", + client_stats: { + "claude-code": { + first_seen: "2026-11-09T10:00:00Z", + last_seen: "2026-11-10T09:30:00Z", + count: 42, + }, + codex: { + first_seen: "2026-11-09T11:00:00Z", + last_seen: "2026-11-09T12:00:00Z", + count: 3, + }, + }, +}; + +/** antd's expand toggle renders as a button with a locale aria-label. */ +function expandButtons(container: HTMLElement): HTMLElement[] { + return Array.from( + container.querySelectorAll(".ant-table-row-expand-icon"), + ); +} + +beforeEach(() => { + vi.clearAllMocks(); + api.list.mockResolvedValue([activeToken]); +}); + +describe("", () => { + it("renders the token hint, unscoped experts and active status", async () => { + render(); + + expect(await screen.findByText("codex@macbook")).toBeInTheDocument(); + expect(screen.getByText("omcp_…abcd")).toBeInTheDocument(); + expect(screen.getByText("不限")).toBeInTheDocument(); + expect(screen.getByText("有效")).toBeInTheDocument(); + expect(screen.getByText("从未使用")).toBeInTheDocument(); + expect(api.list).toHaveBeenCalledTimes(1); + }); + + it("shows the bound expert name, and a count for multi-expert tokens", async () => { + api.list.mockResolvedValue([ + { ...activeToken, token_id: "tok_single", expert_ids: ["agent_b"] }, + { + ...activeToken, + token_id: "tok_multi", + expert_ids: ["agent_a", "agent_b"], + }, + ]); + render(); + + // Single binding renders the expert name; the historical multi-expert row + // renders a count plus one tag per expert. + await waitFor(() => expect(screen.getAllByText("专家乙")).toHaveLength(2)); + expect(screen.getByText("专家甲")).toBeInTheDocument(); + expect(screen.getByText("2 个专家")).toBeInTheDocument(); + }); + + it("shows the one-time plaintext after creating a token", async () => { + api.create.mockResolvedValue({ + token: { + ...activeToken, + token_id: "tok_2", + name: "claude@laptop", + }, + plaintext: "omcp_live_plaintext_value", + }); + const user = userEvent.setup(); + render(); + await screen.findByText("codex@macbook"); + + await user.click(screen.getByRole("button", { name: /创建 Token/ })); + const nameInput = await screen.findByRole("textbox", { name: "名称" }); + await user.type(nameInput, "claude@laptop"); + // The expert picker defaults to the expert currently in view and stays + // single-select; re-pick another one to prove the value is sent. + expect(await screen.findByText("专家乙 · agent_b")).toBeInTheDocument(); + await user.click(screen.getByRole("combobox", { name: "上报专家" })); + await user.click(await screen.findByTitle("专家甲 · agent_a")); + await user.click(screen.getByRole("button", { name: /^创\s*建$/ })); + + await waitFor(() => + expect(api.create).toHaveBeenCalledWith({ + name: "claude@laptop", + expert_ids: ["agent_a"], + }), + ); + expect( + await screen.findByDisplayValue("omcp_live_plaintext_value"), + ).toBeInTheDocument(); + expect(screen.getByText(/只显示这一次/)).toBeInTheDocument(); + // The list is refreshed after a successful create. + await waitFor(() => expect(api.list).toHaveBeenCalledTimes(2)); + }); + + it("switches the reporting expert via PATCH and refreshes the list", async () => { + api.update.mockResolvedValue({ ...activeToken, expert_ids: ["agent_a"] }); + const user = userEvent.setup(); + render(); + await screen.findByText("codex@macbook"); + + await user.click(screen.getByRole("button", { name: /切换专家/ })); + await user.click(await screen.findByRole("combobox", { name: "上报专家" })); + await user.click(await screen.findByTitle("专家甲 · agent_a")); + await user.click(screen.getByRole("button", { name: /^保\s*存$/ })); + + await waitFor(() => + expect(api.update).toHaveBeenCalledWith("tok_1", { + expert_ids: ["agent_a"], + }), + ); + await waitFor(() => expect(api.list).toHaveBeenCalledTimes(2)); + expect(message.success).toHaveBeenCalledWith("已切换上报专家"); + }); + + it("revokes a token via the confirmation and refreshes the list", async () => { + api.revoke.mockResolvedValue({ revoked: true }); + const user = userEvent.setup(); + render(); + await screen.findByText("codex@macbook"); + + await user.click(screen.getByRole("button", { name: /撤\s*销/ })); + // The Popconfirm's ok button shares the "撤销" label; the last one is it. + const revokeButtons = await screen.findAllByRole("button", { + name: /撤\s*销/, + }); + await user.click(revokeButtons[revokeButtons.length - 1]); + + await waitFor(() => expect(api.revoke).toHaveBeenCalledWith("tok_1")); + await waitFor(() => expect(api.list).toHaveBeenCalledTimes(2)); + }); + + it("shows the revoked state and disables row actions for revoked tokens", async () => { + api.list.mockResolvedValue([ + { ...activeToken, revoked_at: "2026-11-09T09:00:00Z" }, + ]); + render(); + + expect(await screen.findByText("已撤销")).toBeInTheDocument(); + expect(screen.getByRole("button", { name: /撤\s*销/ })).toBeDisabled(); + expect(screen.getByRole("button", { name: /切换专家/ })).toBeDisabled(); + }); + + it("expands a token to show each client's name, last use and call count", async () => { + api.list.mockResolvedValue([clientToken]); + const user = userEvent.setup(); + const { container } = render(); + await screen.findByText("claude@laptop"); + + // The 接入端 column counts the distinct clients, before any expansion. + expect(screen.getByText("2")).toBeInTheDocument(); + expect(screen.queryByText("claude-code")).not.toBeInTheDocument(); + + await user.click(expandButtons(container)[0]); + + expect(await screen.findByText("claude-code")).toBeInTheDocument(); + expect(screen.getByText("codex")).toBeInTheDocument(); + expect(screen.getByText("42")).toBeInTheDocument(); + expect(screen.getByText("3")).toBeInTheDocument(); + // last_seen is rendered in the server timezone, not the viewer's. + expect( + screen.getByText( + formatServerIsoDateTime("2026-11-10T09:30:00Z", "Asia/Shanghai"), + ), + ).toBeInTheDocument(); + expect(screen.getAllByRole("switch")).toHaveLength(2); + expect(screen.getByRole("switch", { name: "codex 接入" })).toBeChecked(); + }); + + it("turns a client off through PATCH and refreshes the list", async () => { + api.list.mockResolvedValue([clientToken]); + api.update.mockResolvedValue({ + ...clientToken, + disabled_clients: ["codex"], + }); + const user = userEvent.setup(); + const { container } = render(); + await screen.findByText("claude@laptop"); + await user.click(expandButtons(container)[0]); + + await user.click(await screen.findByRole("switch", { name: "codex 接入" })); + + await waitFor(() => + expect(api.update).toHaveBeenCalledWith("tok_clients", { + disabled_clients: ["codex"], + }), + ); + expect(message.success).toHaveBeenCalledWith("已更新接入端设置"); + await waitFor(() => expect(api.list).toHaveBeenCalledTimes(2)); + }); + + it("sends disabled_clients: null when the last switched-off client is re-enabled", async () => { + api.list.mockResolvedValue([ + { ...clientToken, disabled_clients: ["codex"] }, + ]); + api.update.mockResolvedValue(clientToken); + const user = userEvent.setup(); + const { container } = render(); + await screen.findByText("claude@laptop"); + await user.click(expandButtons(container)[0]); + + const codexSwitch = await screen.findByRole("switch", { + name: "codex 接入", + }); + expect(codexSwitch).not.toBeChecked(); + expect( + screen.getByRole("switch", { name: "claude-code 接入" }), + ).toBeChecked(); + await user.click(codexSwitch); + + await waitFor(() => + expect(api.update).toHaveBeenCalledWith("tok_clients", { + disabled_clients: null, + }), + ); + }); + + it("disables the client switches of a revoked token", async () => { + api.list.mockResolvedValue([ + { ...clientToken, revoked_at: "2026-11-09T09:00:00Z" }, + ]); + const user = userEvent.setup(); + const { container } = render(); + await screen.findByText("claude@laptop"); + await user.click(expandButtons(container)[0]); + + const switches = await screen.findAllByRole("switch"); + expect(switches).toHaveLength(2); + for (const control of switches) expect(control).toBeDisabled(); + }); + + it("explains the empty client list until a client sends its header", async () => { + const user = userEvent.setup(); + const { container } = render(); + await screen.findByText("codex@macbook"); + + await user.click(expandButtons(container)[0]); + + expect( + await screen.findByText( + "还没有接入记录(客户端带上 X-Octop-Client 后才会出现)", + ), + ).toBeInTheDocument(); + }); + + it("copies a token's setup command straight away while its plaintext is cached", async () => { + const freshToken: MemoryMcpToken = { + ...activeToken, + token_id: "tok_2", + name: "claude@laptop", + }; + api.list.mockResolvedValue([activeToken, freshToken]); + api.create.mockResolvedValue({ + token: freshToken, + plaintext: "omcp_live_plaintext_value", + }); + const user = userEvent.setup(); + render(); + await screen.findByText("codex@macbook"); + + // Creating a token is what puts the plaintext in the session cache. + await user.click(screen.getByRole("button", { name: /创建 Token/ })); + await user.type( + await screen.findByRole("textbox", { name: "名称" }), + "claude@laptop", + ); + await user.click(screen.getByRole("button", { name: /^创\s*建$/ })); + await screen.findByDisplayValue("omcp_live_plaintext_value"); + await user.click(screen.getByRole("button", { name: "我已保存,关闭" })); + + // The second row (claude@laptop) is the one with a cached plaintext. + const commandButtons = await screen.findAllByRole("button", { + name: /接入配置/, + }); + await user.click(commandButtons[1]); + + await waitFor(() => + expect(copyMock).toHaveBeenCalledWith( + clientConfig("omcp_live_plaintext_value"), + ), + ); + expect(message.success).toHaveBeenCalledWith("已复制"); + // No modal and no regeneration: the plaintext was still known. + expect(api.rotate).not.toHaveBeenCalled(); + expect( + screen.queryByText(/明文只在创建时显示一次/), + ).not.toBeInTheDocument(); + }); + + it("regenerates the token before copying when the plaintext is unknown", async () => { + api.rotate.mockResolvedValue({ + token: { ...activeToken, token_hint: "omcp_…new0" }, + plaintext: "omcp_rotated_secret", + }); + const user = userEvent.setup(); + render(); + await screen.findByText("codex@macbook"); + + await user.click(screen.getByRole("button", { name: /接入配置/ })); + expect( + await screen.findByText(/明文只在创建时显示一次/), + ).toBeInTheDocument(); + expect(api.rotate).not.toHaveBeenCalled(); + + await user.click(screen.getByRole("button", { name: /重新生成并复制/ })); + + await waitFor(() => expect(api.rotate).toHaveBeenCalledWith("tok_1")); + await waitFor(() => + expect(copyMock).toHaveBeenCalledWith( + clientConfig("omcp_rotated_secret"), + ), + ); + // The new config stays on screen so it can be copied again. + await waitFor(() => { + const areas = Array.from(document.querySelectorAll("textarea")); + expect( + areas.some( + (area) => area.value === clientConfig("omcp_rotated_secret"), + ), + ).toBe(true); + }); + expect(screen.getByText(/旧 Token 已失效/)).toBeInTheDocument(); + + // Closing the modal refreshes the list (token_hint changed server-side). + await user.click(screen.getByRole("button", { name: /关\s*闭/ })); + await waitFor(() => expect(api.list).toHaveBeenCalledTimes(2)); + }); + + it("disables the setup-command action of a revoked token", async () => { + api.list.mockResolvedValue([ + { ...activeToken, revoked_at: "2026-11-09T09:00:00Z" }, + ]); + render(); + + expect(await screen.findByText("已撤销")).toBeInTheDocument(); + expect(screen.getByRole("button", { name: /接入配置/ })).toBeDisabled(); + }); +}); diff --git a/dashboard/src/pages/Agent/Memory/McpAccess.tsx b/dashboard/src/pages/Agent/Memory/McpAccess.tsx new file mode 100644 index 0000000000..2fceec7312 --- /dev/null +++ b/dashboard/src/pages/Agent/Memory/McpAccess.tsx @@ -0,0 +1,1082 @@ +/** + * MCP 接入 — user-level tokens for the memory MCP server. + * + * Embedded as a tab inside MemoryPanel (only when the host page opts in via + * ``showMcpTab``), so the sidebar keeps its existing keys. External agents + * (Claude Code / Codex / Cursor / Kiro / DSH) authenticate against + * ``/mcp/memory`` with the plaintext token; the server only ever shows it once. + */ + +import { useCallback, useEffect, useMemo, useState } from "react"; +import type { CSSProperties } from "react"; +import { + Alert, + Button, + Empty, + Form, + Input, + Modal, + Popconfirm, + Select, + Skeleton, + Space, + Switch, + Table, + Tabs, + Tag, + Typography, +} from "antd"; +import type { TableColumnsType } from "antd"; +import { KeyRound, Plus, Terminal, Trash2, UserRoundCog } from "lucide-react"; +import { useTranslation } from "react-i18next"; + +import { + memoryMcpApi, + type CreateMemoryMcpTokenBody, + type MemoryMcpToken, + type MemoryMcpTokenCreated, +} from "../../../api/modules/memoryMcp"; +import { useAgent } from "../../../context/AgentContext"; +import { useServerTimezone } from "../../../hooks/useServerTimezone"; +import { message } from "@/utils/antdMessage"; +import { copyText } from "../../../utils/copyText"; +import { formatServerIsoDateTime } from "../../../utils/formatMessageTime"; +import styles from "./MemorySettings.module.less"; + +/** + * Sentinel for "no expert binding" in the single-select expert pickers. + * Choosing it sends ``expert_ids: null``, which brings the + * ``X-Octop-Agent-Id`` requirement back on MCP requests. + */ +const UNRESTRICTED_EXPERT = "__unrestricted__"; + +/** Public setup guide for the clients this tab issues tokens to. */ +const MCP_SETUP_DOCS_URL = + "https://github.com/TencentCloud/octop-memory/blob/main/plugins/harness/AI-SETUP.md"; + +interface CreateFormValues { + name: string; + expert_id: string; +} + +interface SwitchExpertFormValues { + expert_id?: string; +} + +/** One row of the expanded client panel: name, last use, calls, toggle. */ +/** 操作列的文字按钮:去掉默认左右内边距,三个按钮挤在一行里也不松散。 */ +const ACTION_TEXT_STYLE = { paddingInline: 4, height: 24 } as const; + +const CLIENT_ROW_STYLE: CSSProperties = { + display: "grid", + gridTemplateColumns: "minmax(120px, 1fr) 190px 72px 52px", + columnGap: 12, + alignItems: "center", +}; + +export default function McpAccess() { + const { t } = useTranslation(); + const timeZone = useServerTimezone(); + const { agents, activeAgentId } = useAgent(); + + const [tokens, setTokens] = useState([]); + const origin = typeof window !== "undefined" ? window.location.origin : ""; + const [loading, setLoading] = useState(true); + const [loadError, setLoadError] = useState<{ detail?: string } | null>(null); + const [createOpen, setCreateOpen] = useState(false); + const [creating, setCreating] = useState(false); + const [createExpertDefault, setCreateExpertDefault] = useState(""); + const [created, setCreated] = useState(null); + /** + * Plaintexts seen this session, keyed by token id. The server keeps only the + * digest, so a row without an entry can only copy after a rotate. + */ + const [plaintextByToken, setPlaintextByToken] = useState< + Record + >({}); + /** Token whose "setup command" modal is open, if any. */ + const [commandTarget, setCommandTarget] = useState( + null, + ); + const [rotating, setRotating] = useState(false); + /** Command to show once the token was regenerated; null before that. */ + const [rotatedCommand, setRotatedCommand] = useState(null); + const [rotatedPlaintext, setRotatedPlaintext] = useState(null); + const [revokingId, setRevokingId] = useState(null); + /** ``token_id:client`` currently being enabled/disabled. */ + const [togglingClient, setTogglingClient] = useState(null); + const [switchTarget, setSwitchTarget] = useState(null); + const [switching, setSwitching] = useState(false); + const [form] = Form.useForm(); + const [switchForm] = Form.useForm(); + + const load = useCallback(async () => { + setLoading(true); + setLoadError(null); + try { + setTokens(await memoryMcpApi.list()); + } catch (e) { + setLoadError({ detail: e instanceof Error ? e.message : undefined }); + } finally { + setLoading(false); + } + }, []); + + useEffect(() => { + void load(); + }, [load]); + + // Token expert_ids are agent ids, so the picker reuses the loaded agent list + // instead of introducing another endpoint. Bridge shadows are excluded: they + // are remote placeholders that cannot own a local memory store. + const expertOptions = useMemo( + () => + agents + .filter((agent) => !agent.bridge) + .map((agent) => ({ + value: agent.agent_id, + label: `${agent.name} · ${agent.agent_id}`, + })), + [agents], + ); + + const expertPickerOptions = useMemo( + () => [ + ...expertOptions, + { + value: UNRESTRICTED_EXPERT, + label: t( + "memory.mcp.expertUnrestricted", + "不限定专家(需客户端带 X-Octop-Agent-Id)", + ), + }, + ], + [expertOptions, t], + ); + + const expertNames = useMemo(() => { + const map = new Map(); + for (const agent of agents) map.set(agent.agent_id, agent.name); + return map; + }, [agents]); + + /** Default for a new token: the expert the user is looking at right now. */ + const defaultExpertId = useMemo(() => { + if (expertOptions.some((option) => option.value === activeAgentId)) { + return activeAgentId as string; + } + return expertOptions[0]?.value ?? UNRESTRICTED_EXPERT; + }, [expertOptions, activeAgentId]); + + const openCreate = () => { + setCreateExpertDefault(defaultExpertId); + setCreateOpen(true); + }; + + // The create modal is destroyed on close, so the default expert can only be + // written once its Form is mounted (same commit as ``createOpen``). + useEffect(() => { + if (!createOpen) return; + form.setFieldsValue({ expert_id: createExpertDefault }); + }, [createOpen, createExpertDefault, form]); + + const openSwitchExpert = (token: MemoryMcpToken) => { + setSwitchTarget(token); + }; + + useEffect(() => { + if (!switchTarget) return; + const ids = switchTarget.expert_ids ?? []; + switchForm.setFieldsValue({ + expert_id: ids.length === 1 ? ids[0] : undefined, + }); + }, [switchTarget, switchForm]); + + const buildClientConfig = ( + plaintext: string, + expertIds?: string[] | null, + ) => { + const headers: Record = { + Authorization: `Bearer ${plaintext}`, + }; + // A token bound to exactly one expert carries its expert in the token; any + // other token needs the expert header, otherwise /mcp/memory returns 400. + if (!expertIds || expertIds.length !== 1) { + headers["X-Octop-Agent-Id"] = "<专家 ID>"; + } + return JSON.stringify( + { + mcpServers: { + "octop-memory": { + type: "http", + url: `${origin}/mcp/memory/`, + headers, + }, + }, + }, + null, + 2, + ); + }; + + const buildInstallScript = (plaintext: string) => + `curl -fsSL https://raw.githubusercontent.com/TencentCloud/octop-memory/main/plugins/harness/install.sh | sh -s -- --url ${origin}/mcp/memory/ --token ${plaintext}`; + + const buildAiPrompt = (plaintext: string) => + [ + "请按 https://raw.githubusercontent.com/TencentCloud/octop-memory/main/plugins/harness/AI-SETUP.md 完成 octop-memory 终端接入。", + `OCTOP_URL=${origin}/mcp/memory/`, + `OCTOP_TOKEN=${plaintext}`, + "安装后按文档里的验证步骤检查召回与上报,并把结果告诉我。", + ].join("\n"); + + const buildInstallPowerShell = (plaintext: string) => + `irm https://raw.githubusercontent.com/TencentCloud/octop-memory/main/plugins/harness/install.ps1 -OutFile install.ps1; .\\install.ps1 -Url ${origin}/mcp/memory/ -Token ${plaintext}`; + + const handleCreate = async () => { + let values: CreateFormValues; + try { + values = await form.validateFields(); + } catch { + return; + } + setCreating(true); + try { + const body: CreateMemoryMcpTokenBody = { + name: values.name.trim(), + // A token bound to exactly one expert needs no agent header on MCP + // requests; null means "unrestricted", which still requires it. + expert_ids: + values.expert_id === UNRESTRICTED_EXPERT ? null : [values.expert_id], + }; + const result = await memoryMcpApi.create(body); + setCreateOpen(false); + form.resetFields(); + setCreated(result); + // Keep the secret for this session so the row can copy its command again. + setPlaintextByToken((prev) => ({ + ...prev, + [result.token.token_id]: result.plaintext, + })); + await load(); + } catch (e) { + message.error( + e instanceof Error + ? e.message + : t("memory.mcp.createFailed", "创建失败,请重试"), + ); + } finally { + setCreating(false); + } + }; + + const handleSwitchExpert = async () => { + if (!switchTarget) return; + let values: SwitchExpertFormValues; + try { + values = await switchForm.validateFields(); + } catch { + return; + } + const expertId = values.expert_id; + setSwitching(true); + try { + await memoryMcpApi.update(switchTarget.token_id, { + expert_ids: + !expertId || expertId === UNRESTRICTED_EXPERT ? null : [expertId], + }); + message.success(t("memory.mcp.switchExpertSuccess", "已切换上报专家")); + setSwitchTarget(null); + switchForm.resetFields(); + await load(); + } catch (e) { + message.error( + e instanceof Error + ? e.message + : t("memory.mcp.switchExpertFailed", "切换失败,请重试"), + ); + } finally { + setSwitching(false); + } + }; + + const handleCopy = async () => { + if (!created) return; + const ok = await copyText(created.plaintext); + if (ok) { + message.success(t("memory.mcp.copied", "已复制")); + } else { + message.error(t("memory.mcp.copyFailed", "复制失败,请手动选中后复制")); + } + }; + + const copySetupCommand = async (command: string) => { + const ok = await copyText(command); + if (ok) { + message.success(t("memory.mcp.copied", "已复制")); + } else { + message.error(t("memory.mcp.copyFailed", "复制失败,请手动选中后复制")); + } + }; + + const handleCommandClick = (token: MemoryMcpToken) => { + const plaintext = plaintextByToken[token.token_id]; + if (plaintext) { + void copySetupCommand(buildClientConfig(plaintext, token.expert_ids)); + return; + } + setRotatedCommand(null); + setRotatedPlaintext(null); + setCommandTarget(token); + }; + + const handleRegenerateCommand = async () => { + if (!commandTarget) return; + setRotating(true); + try { + const result = await memoryMcpApi.rotate(commandTarget.token_id); + const command = buildClientConfig( + result.plaintext, + result.token.expert_ids, + ); + setPlaintextByToken((prev) => ({ + ...prev, + [result.token.token_id]: result.plaintext, + })); + setRotatedCommand(command); + setRotatedPlaintext(result.plaintext); + await copySetupCommand(command); + } catch (e) { + message.error( + e instanceof Error + ? e.message + : t("memory.mcp.rotateFailed", "重新生成失败,请重试"), + ); + } finally { + setRotating(false); + } + }; + + const closeCommandModal = () => { + if (rotating) return; + const rotated = rotatedCommand !== null; + setCommandTarget(null); + setRotatedCommand(null); + setRotatedPlaintext(null); + // A rotate rewrote token_hint and cleared last_used_at. + if (rotated) void load(); + }; + + const handleRevoke = async (token: MemoryMcpToken) => { + setRevokingId(token.token_id); + try { + await memoryMcpApi.revoke(token.token_id); + message.success(t("memory.mcp.revoked", "Token 已撤销")); + await load(); + } catch (e) { + message.error( + e instanceof Error + ? e.message + : t("memory.mcp.revokeFailed", "撤销失败,请重试"), + ); + } finally { + setRevokingId(null); + } + }; + + /** + * Enable/disable one client for a token. + * + * The Switch is driven by ``token.disabled_clients`` from the list state, so + * a failed PATCH needs no explicit rollback: the row keeps the server value + * and the switch snaps back once loading clears. + */ + const handleToggleClient = async ( + token: MemoryMcpToken, + client: string, + enabled: boolean, + ) => { + const disabled = new Set(token.disabled_clients ?? []); + if (enabled) disabled.delete(client); + else disabled.add(client); + setTogglingClient(`${token.token_id}:${client}`); + try { + await memoryMcpApi.update(token.token_id, { + // An empty list means "nothing switched off", which the API spells null. + disabled_clients: disabled.size > 0 ? [...disabled] : null, + }); + message.success(t("memory.mcp.clientsUpdated", "已更新接入端设置")); + await load(); + } catch (e) { + message.error( + e instanceof Error + ? e.message + : t("memory.mcp.clientsUpdateFailed", "更新接入端设置失败,请重试"), + ); + } finally { + setTogglingClient(null); + } + }; + + const renderClients = (token: MemoryMcpToken) => { + const entries = Object.entries(token.client_stats ?? {}); + if (entries.length === 0) { + return ( + + {t( + "memory.mcp.clientsEmpty", + "还没有接入记录(客户端带上 X-Octop-Client 后才会出现)", + )} + + ); + } + const disabled = new Set(token.disabled_clients ?? []); + return ( +
+
+ + {t("memory.mcp.clientColumnName", "客户端")} + + + {t("memory.mcp.clientColumnLastSeen", "最近使用")} + + + {t("memory.mcp.clientColumnCount", "次数")} + + + {t("memory.mcp.clientColumnEnabled", "启用")} + +
+ {entries.map(([client, stat]) => ( +
+ {client} + {formatServerIsoDateTime(stat.last_seen, timeZone)} + {stat.count} + + + void handleToggleClient(token, client, checked) + } + /> + +
+ ))} +
+ ); + }; + + const columns: TableColumnsType = [ + { + title: t("memory.mcp.columnName", "名称"), + dataIndex: "name", + key: "name", + render: (name: string) => ( + {name} + ), + }, + { + title: t("memory.mcp.columnHint", "Token 提示"), + dataIndex: "token_hint", + key: "token_hint", + render: (hint: string) => {hint}, + }, + { + title: t("memory.mcp.columnExperts", "上报专家"), + dataIndex: "expert_ids", + key: "expert_ids", + render: (_: unknown, token) => { + const ids = token.expert_ids ?? []; + if (ids.length === 0) { + return {t("memory.mcp.allExperts", "不限")}; + } + if (ids.length === 1) { + const id = ids[0]; + return {expertNames.get(id) ?? id}; + } + // Historical tokens may still carry several experts; keep them legible + // without pretending there is a single binding. + return ( + + + {t("memory.mcp.expertCount", "{{count}} 个专家", { + count: ids.length, + })} + + {ids.map((id) => ( + + {expertNames.get(id) ?? id} + + ))} + + ); + }, + }, + { + title: t("memory.mcp.columnClients", "接入端"), + key: "clients", + width: 100, + render: (_: unknown, token) => { + const count = Object.keys(token.client_stats ?? {}).length; + return count > 0 ? ( + {count} + ) : ( + - + ); + }, + }, + { + title: t("memory.mcp.columnCreatedAt", "创建时间"), + dataIndex: "created_at", + key: "created_at", + render: (value: string) => ( + {formatServerIsoDateTime(value, timeZone)} + ), + }, + { + title: t("memory.mcp.columnLastUsedAt", "最近使用"), + dataIndex: "last_used_at", + key: "last_used_at", + render: (value: string | null) => + value ? ( + {formatServerIsoDateTime(value, timeZone)} + ) : ( + + {t("memory.mcp.neverUsed", "从未使用")} + + ), + }, + { + title: t("memory.mcp.columnStatus", "状态"), + dataIndex: "revoked_at", + key: "status", + render: (revokedAt: string | null) => + revokedAt ? ( + {t("memory.mcp.statusRevoked", "已撤销")} + ) : ( + {t("memory.mcp.statusActive", "有效")} + ), + }, + { + title: t("memory.mcp.columnActions", "操作"), + key: "actions", + width: 276, + render: (_: unknown, token) => ( + + + + void handleRevoke(token)} + > + + + + ), + }, + ]; + + return ( +
+
+ + + +
+

{t("memory.mcp.title", "终端接入")}

+

+ {t( + "memory.mcp.description", + "外部 Agent(Claude Code / Codex / Cursor / Kiro / DSH)使用这里的 Token 访问 {{endpoint}}。Token 只显示一次,丢失后请重建。", + { endpoint: "/mcp/memory" }, + )} + + {t("memory.mcp.docsLink", "接入说明")} + +

+
+ +
+ + {loadError ? ( + void load()}> + {t("common.retry", "重试")} + + } + /> + ) : null} + + {loading && tokens.length === 0 ? ( + + ) : ( + + rowKey="token_id" + size="middle" + loading={loading} + columns={columns} + dataSource={tokens} + pagination={false} + expandable={{ expandedRowRender: renderClients, columnWidth: 48 }} + scroll={{ x: 1120 }} + locale={{ + emptyText: ( + + + {t("memory.mcp.empty", "还没有 MCP Token")} + + + {t( + "memory.mcp.emptyHint", + "创建后即可在外部 Agent 中接入你的记忆。", + )} + + + } + > + + + ), + }} + /> + )} + + void handleCreate()} + onCancel={() => { + if (creating) return; + setCreateOpen(false); + form.resetFields(); + }} + destroyOnHidden + > +
+ + + + + + +
+ + ) : null} +
+ + setCreated(null)} + footer={ + + + + + } + > + {created ? ( + + + {created.token.name} + + {t("memory.mcp.tokenLabel", "Token")} + + + + + + + {t( + "memory.mcp.commandReady", + "请先复制并保存上面的 Token(关闭后无法再次查看)。接入时任选一种方式:", + )} + + + + + + ), + }, + { + key: "windows", + label: "Windows", + children: ( + + + + + ), + }, + { + key: "ai", + label: t("memory.mcp.aiInstall", "交给 AI"), + children: ( + + + + + ), + }, + { + key: "json", + label: t("memory.mcp.manualConfig", "手动配置"), + children: ( + <> + + + + + {(created.token.expert_ids?.length ?? 0) !== 1 && ( +
+ {t( + "memory.mcp.unboundHint", + "该 Token 未绑定唯一专家:安装脚本不可用,请用此手动配置并把 <专家 ID> 换成要访问的专家。", + )} +
+ )} + + ), + }, + ]} + /> +
+ ) : null} +
+ + void handleRegenerateCommand()} + onCancel={closeCommandModal} + okButtonProps={{ danger: true }} + footer={ + rotatedCommand ? ( + + ) : undefined + } + destroyOnHidden + > + {commandTarget ? ( + + + {commandTarget.name} · {commandTarget.token_hint} + + {rotatedCommand ? ( + <> + + + {t("memory.mcp.tokenLabel", "Token")} + + + + + + + {t( + "memory.mcp.commandReady", + "一键安装命令(已带上这个 Token,可直接粘贴执行):", + )} + + + + + + + ) : ( + + )} + + ) : null} + +
+ ); +} diff --git a/dashboard/src/pages/Agent/Memory/MemoryPanel.tsx b/dashboard/src/pages/Agent/Memory/MemoryPanel.tsx index b513f04e5a..9f937d626b 100644 --- a/dashboard/src/pages/Agent/Memory/MemoryPanel.tsx +++ b/dashboard/src/pages/Agent/Memory/MemoryPanel.tsx @@ -49,7 +49,8 @@ type MemoryTab = | "journal" | "conversations" | "proactive" - | "settings"; + | "settings" + | "mcp"; type LibraryView = "tree" | "atoms" | "raw"; @@ -135,6 +136,7 @@ export interface MemoryPanelProps { agentId: string | null; /** Stretch tabs to fill parent height (desktop PageShell / drawer). */ fill?: boolean; + /** Show the user-level "MCP access" tab (personal memory page only). */ } /** Memory tabs. Managed experts use the same pages; memory stays off until enabled. */ diff --git a/dashboard/src/pages/Agent/Memory/MemorySettings.module.less b/dashboard/src/pages/Agent/Memory/MemorySettings.module.less index 9ac0d5b6d2..64e880d21d 100644 --- a/dashboard/src/pages/Agent/Memory/MemorySettings.module.less +++ b/dashboard/src/pages/Agent/Memory/MemorySettings.module.less @@ -244,3 +244,13 @@ .backupPath { overflow-wrap: anywhere; } + +/* 接入端开关:固定占位宽度,避免在 grid 里被压缩或撑开列宽 */ +.clientSwitch { + display: inline-flex; + align-items: center; + justify-content: flex-start; + min-width: 44px; + max-width: 44px; + overflow: hidden; +} diff --git a/dashboard/src/pages/Settings/Tokens/index.tsx b/dashboard/src/pages/Settings/Tokens/index.tsx new file mode 100644 index 0000000000..288327d9e9 --- /dev/null +++ b/dashboard/src/pages/Settings/Tokens/index.tsx @@ -0,0 +1,22 @@ +import McpAccess from "../../Agent/Memory/McpAccess"; + +/** + * 终端接入(设置 → 终端接入)。 + * + * token 是用户级的:一人一份,绑定专家只是它的一个字段。放在设置里而不是某个 + * 专家的记忆面板里,避免「这是某个专家的配置」的误解,也避免每个专家页重复入口。 + */ +export default function TokensPage() { + return ( +
+ +
+ ); +} diff --git a/dashboard/src/routes/index.tsx b/dashboard/src/routes/index.tsx index 3c08a6d85b..c20e678e58 100644 --- a/dashboard/src/routes/index.tsx +++ b/dashboard/src/routes/index.tsx @@ -20,6 +20,8 @@ const RemoteDesktopPage = lazy(() => import("../pages/Control/RemoteDesktop")); // Lazy-loaded pages — Settings const ModelsPage = lazy(() => import("../pages/Settings/Models")); +const TokensPage = lazy(() => import("../pages/Settings/Tokens")); + // Lazy-loaded pages — Admin const OctopAdminUsersPage = lazy(() => import("../pages/Admin/Users")); const AdminSecurityPage = lazy(() => import("../pages/Settings/Security")); @@ -85,6 +87,7 @@ export const pathToKey: Record = { "/subagents": "personalization", "/mbti": "personalization", "/memory": "personalization", + "/tokens": "tokens", // Admin "/admin/models": "models", // Admin @@ -213,6 +216,7 @@ export const routeConfigs: RouteConfig[] = [ path: "/memory", element: , }, + { path: "/tokens", element: }, { path: "/workspace", element: }, // Settings diff --git a/dashboard/src/utils/permissions.ts b/dashboard/src/utils/permissions.ts index 52173a0e81..0e22ab4aad 100644 --- a/dashboard/src/utils/permissions.ts +++ b/dashboard/src/utils/permissions.ts @@ -108,6 +108,7 @@ export const NAV_PERMISSIONS = { experts: PERM.experts, tasks: PERM.tasks, "token-usage": PERM.tokenUsage, + tokens: PERM.memory, personalization: PERM.personalization, channels: PERM.channels, connectors: PERM.connectors, @@ -244,6 +245,9 @@ export function pathPermissionKeys(pathname: string): PermissionKeys | null { if (pathname.startsWith("/admin/")) { return "admin"; } + if (pathname === "/tokens" || pathname.startsWith("/tokens/")) { + return PERM.memory; + } if (pathname === "/channels" || pathname.startsWith("/channels/")) { return PERM.channels; } diff --git a/docs/memory-mcp.md b/docs/memory-mcp.md new file mode 100644 index 0000000000..410ca80d52 --- /dev/null +++ b/docs/memory-mcp.md @@ -0,0 +1,180 @@ +# 专家记忆 MCP Server + +Octop 把专家记忆通过 MCP(Model Context Protocol)开放给外部 Agent / Bot:Claude Code、Codex、DSH 这类编码助手可以和 Octop 专家共用同一份长期记忆。 + + +- 端点:`/mcp/memory`(Streamable HTTP,**stateless**:每次请求独立,服务重启后客户端不会因为 `Mcp-Session-Id` 失效而报 `-32600 Session not found`) +- 专家选择:**token 直接绑定一个专家**(在 Dashboard「记忆 → MCP 接入」建 token 时选,之后可随时切换);客户端不再需要专家 ID +- 调用者身份:**用户级 token**(`Authorization: Bearer omcp_…`),不是实例共享 token;`X-Octop-User-Id` 不再被信任 +- 接入端:hooks / 原生插件会带 `X-Octop-Client: `;Dashboard 可看到每个 token 被哪些接入端用过,并按接入端启用/禁用 + +## 1. 鉴权模型 + +每个 Octop 用户可以有多个 token,每个 token 带一个客户端名字(如 `codex@macbook`),可以: + +- 绑定一个专家(`expert_ids` 恰好 1 个):客户端只带 token 就能用,服务端按绑定路由 +- 也可以不绑(`null`)或绑多个(高级用法):此时客户端必须带 `X-Octop-Agent-Id` 指定这次用哪个 +- 随时在 Dashboard 上**切换 token 绑定的专家**(`PATCH /api/memory-mcp/tokens/`),下一次请求立即生效 +- 单独吊销某一个客户端,不影响其它客户端 +- 追溯每一条记忆是哪个客户端写的(`payload.caller` 是用户,`payload.source_host` 取 token 名字,不依赖客户端自报) + +服务端只保存 token 的 sha256;校验用常量时间比较。**明文只在创建时返回一次**。 + +### 1.1 创建 / 列出 / 吊销 token + +登录 Octop 后调用(`` 是 Octop 的登录 token,与 MCP token 不是一回事): + +```bash +# 创建:返回一次性明文 token +curl -sS -X POST "https:///api/memory-mcp/tokens" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"name": "codex@macbook", "expert_ids": ["Z026BY"]}' + +# 列出(不含明文) +curl -sS "https:///api/memory-mcp/tokens" \ + -H "Authorization: Bearer " + +# 切换这个 token 绑定的专家(也可只改 name) +curl -sS -X PATCH "https:///api/memory-mcp/tokens/" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"expert_ids": ["<另一个专家ID>"]}' + +# 吊销 +curl -sS -X DELETE "https:///api/memory-mcp/tokens/" \ + -H "Authorization: Bearer " +``` + +`POST` 响应里的 `token` 字段形如 `omcp_…`,之后只显示 `token_hint`(`omcp_abcd…wxyz`)。 + +### 1.2 开启挂载 + +`/mcp/memory` 默认不挂载(fail-closed,对现有部署零影响):只有设置环境变量 +`OCTOP_MEMORY_MCP_ENABLED=1` 才挂载(进程启动时判定,设置后重启一次 Octop 生效)。 +挂载后创建 / 轮换 token、切换专家都立即生效,不需要再重启。 + +## 2. 客户端配置 + +任何支持 Streamable HTTP MCP 的客户端都可以接入,只需两样东西: + +| 配置 | 值 | +|------|----| +| URL | `https:///mcp/memory/`(或自建入口,见 §5) | +| Header `Authorization` | `Bearer omcp_…`(§1.1 创建、已绑定专家的那个 token) | + +> 只有「不限专家」或「绑定了多个专家」的 token 才需要额外带 `X-Octop-Agent-Id`;绑定单个专家的 token 只靠 token 就够了。 + +### 2.1 Claude Code + +```bash +claude mcp add --transport http octop-memory "https:///mcp/memory/" \ + --header "Authorization: Bearer omcp_…" +``` + +### 2.2 Codex + +`~/.codex/config.toml`: + +```toml +[mcp_servers.octop-memory] +url = "https:///mcp/memory/" +http_headers = { Authorization = "Bearer omcp_…" } +``` + +### 2.3 DSH / Cursor / Kiro / 其它客户端 + +在客户端的 MCP 配置里填 §2 的 URL 与 `Authorization` 即可(DSH 的 `mcpServers` 用 `type: "streamable-http"`)。 + +### 2.4 一键接入(客户端插件,推荐) + +安装器在 octop-memory 仓库的 `plugins/harness`,不经过服务端,token 由你在运行时传入。 + +macOS / Linux: + +```bash +curl -fsSL https://raw.githubusercontent.com/TencentCloud/octop-memory/main/plugins/harness/install.sh \ + | sh -s -- --url https:///mcp/memory/ --token omcp_… +``` + +Windows PowerShell: + +```powershell +irm https://raw.githubusercontent.com/TencentCloud/octop-memory/main/plugins/harness/install.ps1 -OutFile install.ps1 +.\install.ps1 -Url https:///mcp/memory/ -Token omcp_… +``` + +只装部分终端加 `--terminals claude-code,codex`;装到项目加 `--project "$PWD"`。 +把 [AI-SETUP.md](https://github.com/TencentCloud/octop-memory/blob/main/plugins/harness/AI-SETUP.md) +连同 token 一起交给 AI,也可以自动完成安装。 + +### 2.5 hooks / 安装器(客户端侧) + +自动召回、会话上报、一键安装和各终端适配属于**客户端侧**代码,已从本仓拆出: + +- 安装器与 hooks:`octop-memory` 仓库的 `plugins//` +- DSH 原生插件 `dsh-octop-memory`:独立仓库 发布(npm + GitHub Release) + +本仓库只提供 MCP 服务端、用户级 token 与 Dashboard 管理页;没有安装器也能用(§2 的手动配置即可)。 + +## 3. 工具清单## 3. 工具清单 + +### 3.1 日常工具(任何 token 可用) + +| 工具 | 作用 | +|------|------| +| `memory_search(query, max_results=5, corpus="all")` | 检索记忆,返回带虚拟 `path` 的命中(`corpus=raw` 只看原始事件) | +| `memory_get(path, start=None, lines=None)` | 把命中里的 `path` 解析成 markdown 全文 | +| `memory_save(content, source, topic=None, supersedes=None)` | 显式保存一条事实(跳过提炼,立即可召回;`supersedes` 用于更正) | +| `memory_capture(content="", source="", session_id=None, assistant=None, thread_id=None, dry_run=False, extract=True, events=None)` | 写原始事件(L0),交给提炼管线;默认**不自动晋升**。`events` 可传客户端已解析好的事件列表,单次最多 **200 条**(`OCTOP_MEMORY_CAPTURE_MAX_EVENTS` 可调),超限直接报错,客户端需分批并只在成功后推进 offset;同一 `(专家, 调用者, 会话)` 内按 `payload.src_key`(缺失时用内容哈希)去重,重试不会重复写 L0 | + +### 3.2 审核 / 运维工具(**仅专家所有者**) + +| 工具 | 作用 | +|------|------| +| `memory_raws(...)` | 查 L0 原始事件(FTS / 按会话、host、调用者过滤) | +| `memory_candidates(status=None, ...)` | 查 L1 候选(默认 pending) | +| `memory_extract(session_id=None, promote=None)` | 手动触发提炼;专家未运行时直接报错(不会为提炼启动专家) | +| `memory_promote(candidate_ids)` | 采纳候选(与记忆面板同一套实现) | +| `memory_reject(candidate_id, reason=..., actor=None)` | 忽略候选 | + +外部 agent 默认只应该拿到 §3.1 的四个工具;把审核工具(能自己晋升自己写的内容)留给专家所有者。 + +## 4. 记忆分层与选工具 + +| 层 | 内容 | 读 | 写 | +|----|------|----|----| +| L0 原始事件 | 一轮对话 / 一条记录 | `memory_raws`、`memory_search(corpus="raw")` | `memory_capture` | +| L1 候选 | 提炼出的候选断言 | `memory_candidates` | `memory_extract` | +| L2 原子 / L3 主题页 | 长期记忆 | `memory_search`、`memory_get` | `memory_save`、`memory_promote` | + +- 想把一段对话沉淀成记忆 → `memory_capture`,之后到记忆面板审核 +- 已经确定的事实 → `memory_save` +- 想找背景 → `memory_search`;要原文 → `memory_get` / `memory_raws` + +## 5. 部署与自建入口 + +- 反代 / ingress 只需暴露 `/mcp/memory`(以及给用户创建 token 用的 `/api/memory-mcp/tokens`) +- 客户端条目要指向别的地址(如公网入口)时,设置环境变量 `OCTOP_MEMORY_PUBLIC_MCP_URL`,或实例 `config.json` 的 `memory_public_mcp_url` +- token 的专家范围在创建时就固定;要调整请新建 token 并吊销旧的 + +## 6. 行为契约 + +- **脱敏**:`memory_capture` 走 octop-memory 的 capture 应用层,`redact_secrets` 默认开启,API key / token / password 会在入库前被替换 +- **回声保护**:带上游召回标记(`## Memory Recall` / `[memory] Earlier in this workspace`)的内容不会入库 +- **审核队列**:外部写入默认不自动晋升;是否晋升跟随专家自己的提炼配置 +- **不自动启动专家**:专家停止时 capture 仍写 L0,但不会触发提炼、也不会为了提炼把专家拉起来(避免意外模型费用) +- **权限**:token 属于某个用户;每次请求都会重新校验该用户对目标专家的访问权(自己的 / 共享的专家 / 管理员),改 header 无法越权 + +## 7. 拆分说明(review 后的计划) + +原 PR 把记忆 MCP、召回补丁、对话记录解析、终端安装器/hooks 放在了一起。按 review 建议拆成: + +| PR | 内容 | 目标仓库 | 状态 | +|----|------|----------|------| +| a | MCP 服务端 + 用户级鉴权 + token 管理 UI + 文档(本文档) | Octop | 本 PR | +| b | 召回质量优化(实体后缀 / 强 token 排序) | octop-memory | 待提 | +| c | 对话记录解析 + 终端安装器 / hooks(`plugins//`) | octop-memory | 待提 | +| d | DSH 原生插件 `octop-memory-native` | 独立仓库 | 已拆分 | + +服务端不依赖客户端增强:任何支持 Streamable HTTP MCP 的客户端按 §2 手动配置即可接入。 diff --git a/src/octop/api/app.py b/src/octop/api/app.py index c11fea1300..8e429c0045 100644 --- a/src/octop/api/app.py +++ b/src/octop/api/app.py @@ -199,6 +199,7 @@ async def acme_http01_challenge(token: str) -> PlainTextResponse: mbti, media_generation, memory, + memory_mcp, memory_portable, memory_storage, mobile, @@ -300,6 +301,7 @@ async def acme_http01_challenge(token: str) -> PlainTextResponse: _RouterMount(workspace.router, "/api", ["workspace"]), _RouterMount(agent_files.router, "/api", ["agent_files"]), _RouterMount(memory.router, "/api", ["memory"]), + _RouterMount(memory_mcp.router, "/api", ["memory"]), _RouterMount(memory_portable.router, "/api", ["memory"]), _RouterMount(memory_storage.router, "/api", ["memory"]), _RouterMount(proactive_care.router, "/api", ["proactive-care"]), @@ -327,6 +329,12 @@ async def acme_http01_challenge(token: str) -> PlainTextResponse: ], ) + # 专家记忆 MCP server:用户级 token 鉴权;未开启或没有 token 时不挂载。 + # lifespan 由 install_memory_mcp 串进现有的 FastAPI lifespan,不覆盖它。 + from octop.infra.agents.memory_mcp import install_memory_mcp + + install_memory_mcp(app, server) + if enable_api_docs: @app.get("/api/docs", include_in_schema=False) diff --git a/src/octop/api/common/agent.py b/src/octop/api/common/agent.py index abcee21692..b087996ab0 100644 --- a/src/octop/api/common/agent.py +++ b/src/octop/api/common/agent.py @@ -5,14 +5,15 @@ from typing import Any from octop.infra.errors import ErrorCode, OctopError - - -def agent_is_shared(row: Any) -> bool: - return int(getattr(row, "is_shared", 0) or 0) == 1 - - -def user_owns_agent(row: Any, user: Any) -> bool: - return row.user_id is not None and row.user_id == user.id +from octop.infra.users.access import ( + agent_is_shared as agent_is_shared, # re-exported for routers/tests +) +from octop.infra.users.access import ( + user_may_access_agent, +) +from octop.infra.users.access import ( + user_owns_agent as user_owns_agent, # re-exported for routers/tests +) def assert_agent_owner(row: Any, user: Any) -> None: @@ -24,17 +25,7 @@ def assert_agent_owner(row: Any, user: Any) -> None: def _user_may_access(row: Any, user: Any, *, repos: Any | None = None) -> bool: - if user.is_admin: - return True - if row.user_id is not None and row.user_id == user.id: - return True - if not agent_is_shared(row): - return False - if repos is None: - return True - from octop.infra.users.groups import expert_visible_to # noqa: PLC0415 - - return expert_visible_to(repos, row, user_id=user.id, is_admin=False) + return user_may_access_agent(row, user, repos=repos) def assert_agent_access_row(row: Any, user: Any, *, repos: Any | None = None) -> None: diff --git a/src/octop/api/routers/memory_mcp.py b/src/octop/api/routers/memory_mcp.py new file mode 100644 index 0000000000..94a3d09f3c --- /dev/null +++ b/src/octop/api/routers/memory_mcp.py @@ -0,0 +1,283 @@ +"""User-level API tokens for the memory MCP server. + +Tokens are personal: a caller acts as the user the token was issued to, so +``X-Octop-User-Id`` is never trusted. Only the SHA-256 digest is stored; the +plaintext token is returned once, at creation. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from fastapi import APIRouter, Depends, status +from pydantic import BaseModel, Field, model_validator + +from octop.api.common.agent import assert_agent_access_row +from octop.api.deps import current_user, get_server, require_permission +from octop.infra.agents.memory_tokens import generate_token, token_hint +from octop.infra.errors import ErrorCode, OctopError +from octop.infra.server import OctopServer +from octop.infra.users.identity import User +from octop.infra.utils.ulid import new_ulid + +if TYPE_CHECKING: + from octop.infra.db.repos.memory_mcp_tokens import MemoryMcpTokenRow + +router = APIRouter( + prefix="/memory-mcp/tokens", + dependencies=[Depends(require_permission("memory"))], +) + + +class TokenCreateBody(BaseModel): + name: str = Field( + min_length=1, + max_length=64, + description="Client name shown in the token list, e.g. `codex@macbook`.", + ) + expert_ids: list[str] | None = Field( + default=None, + description=( + "Experts this token may use. Null or empty means every expert " + "the issuing user can access." + ), + ) + + +class TokenPatchBody(BaseModel): + name: str | None = Field( + default=None, + min_length=1, + max_length=64, + description="New client name; omit to keep the current one.", + ) + expert_ids: list[str] | None = Field( + default=None, + description=( + "New expert allow-list. Null or empty removes the restriction " + "(every expert the user can access). Omit to keep the current list." + ), + ) + disabled_clients: list[str] | None = Field( + default=None, + description=( + "Client names (the `X-Octop-Client` header) this token refuses with 403. " + "Null or empty allows every client. Omit to keep the current list." + ), + ) + + @model_validator(mode="after") + def _require_a_field(self) -> TokenPatchBody: + if not self.model_fields_set.intersection({"name", "expert_ids", "disabled_clients"}): + raise ValueError("provide name and/or expert_ids and/or disabled_clients") + if "name" in self.model_fields_set and self.name is None: + raise ValueError("name must not be null") + return self + + +class TokenOut(BaseModel): + token_id: str = Field(description="Public token id used to revoke it.") + name: str = Field(description="Client name supplied at creation.") + expert_ids: list[str] | None = Field( + default=None, + description="Expert allow-list; null means no restriction.", + ) + disabled_clients: list[str] | None = Field( + default=None, + description="Clients refused with 403; null means every client is allowed.", + ) + client_stats: dict[str, dict[str, Any]] | None = Field( + default=None, + description=( + "Per-client usage seen through `X-Octop-Client`: " + "`{client: {first_seen, last_seen, count}}`; null until a client identifies itself." + ), + ) + token_hint: str = Field(description="Masked token for display, e.g. `omcp_abcd…wxyz`.") + created_at: str = Field(description="Creation time (ISO-8601 UTC).") + last_used_at: str | None = Field(default=None, description="Last authenticated use.") + revoked_at: str | None = Field(default=None, description="Revocation time, if revoked.") + + +class TokenCreated(TokenOut): + token: str = Field( + description="Plaintext token. Returned only once; the server keeps only its digest." + ) + + +class TokenRevoked(BaseModel): + revoked: bool = Field(description="True when this call revoked the token.") + + +def _to_out(row: MemoryMcpTokenRow) -> TokenOut: + return TokenOut( + token_id=row.token_id, + name=row.name, + expert_ids=row.expert_ids, + disabled_clients=row.disabled_clients, + client_stats=row.client_stats, + token_hint=row.token_hint, + created_at=row.created_at, + last_used_at=row.last_used_at, + revoked_at=row.revoked_at, + ) + + +def _assert_experts_accessible(repos: Any, expert_ids: list[str] | None, user: User) -> None: + """Every expert in the allow-list must exist and be visible to *user*.""" + for expert_id in expert_ids or []: + row = repos.agent_repo.get(expert_id) + if row is None: + raise OctopError(ErrorCode.AGENT_NOT_FOUND, f"agent {expert_id!r} not found") + assert_agent_access_row(row, user, repos=repos) + + +@router.post( + "", + status_code=status.HTTP_201_CREATED, + response_model=TokenCreated, + summary="Create a memory MCP token", + description="Issues a personal token for one MCP client. The plaintext token is returned once.", +) +def create_token( + body: TokenCreateBody, + user: User = Depends(current_user), + server: OctopServer = Depends(get_server), +) -> TokenCreated: + assert server.services is not None + repos = server.services.repos + _assert_experts_accessible(repos, body.expert_ids, user) + + plaintext, token_hash = generate_token() + token_row = repos.memory_mcp_token_repo.create( + user_id=user.id, + name=body.name, + expert_ids=body.expert_ids or None, + token_id=new_ulid(), + token_hash=token_hash, + token_hint=token_hint(plaintext), + ) + return TokenCreated(**_to_out(token_row).model_dump(), token=plaintext) + + +@router.get( + "", + response_model=list[TokenOut], + summary="List my memory MCP tokens", + description="Lists every token issued by the caller, including revoked ones.", +) +def list_tokens( + user: User = Depends(current_user), + server: OctopServer = Depends(get_server), +) -> list[TokenOut]: + assert server.services is not None + rows = server.services.repos.memory_mcp_token_repo.list_for_user(user.id) + return [_to_out(row) for row in rows] + + +@router.patch( + "/{token_id}", + response_model=TokenOut, + summary="Update a memory MCP token", + description=( + "Renames one of the caller's own tokens and/or rebinds its expert allow-list, " + "and/or disables specific clients (the `X-Octop-Client` header). " + "Binding a token to a single expert makes it a 唯一令牌: MCP clients then omit " + "`X-Octop-Agent-Id`. Other users' tokens are not found; revoked tokens cannot be " + "edited." + ), +) +def update_token( + token_id: str, + body: TokenPatchBody, + user: User = Depends(current_user), + server: OctopServer = Depends(get_server), +) -> TokenOut: + assert server.services is not None + repos = server.services.repos + repo = repos.memory_mcp_token_repo + row = repo.get_for_user(token_id, user_id=user.id) + if row is None: + raise OctopError(ErrorCode.NOT_FOUND, f"memory MCP token {token_id!r} not found") + if row.revoked_at: + raise OctopError( + ErrorCode.FORBIDDEN, + f"memory MCP token {token_id!r} was revoked and can no longer be edited", + status=409, + ) + + name = row.name + if "name" in body.model_fields_set: + assert body.name is not None # guaranteed by TokenPatchBody + name = body.name + expert_ids = row.expert_ids + if "expert_ids" in body.model_fields_set: + expert_ids = body.expert_ids or None + _assert_experts_accessible(repos, expert_ids, user) + disabled_clients = row.disabled_clients + if "disabled_clients" in body.model_fields_set: + disabled_clients = body.disabled_clients or None + + updated = repo.update( + token_id, + user_id=user.id, + name=name, + expert_ids=expert_ids, + disabled_clients=disabled_clients, + ) + if updated is None: + raise OctopError(ErrorCode.NOT_FOUND, f"memory MCP token {token_id!r} not found") + return _to_out(updated) + + +@router.post( + "/{token_id}/rotate", + response_model=TokenCreated, + summary="Rotate a memory MCP token", + description=( + "Issues a fresh secret for one of the caller's own tokens; the previous plaintext " + "stops working immediately. Revoked tokens cannot be rotated." + ), +) +def rotate_token( + token_id: str, + user: User = Depends(current_user), + server: OctopServer = Depends(get_server), +) -> TokenCreated: + assert server.services is not None + repo = server.services.repos.memory_mcp_token_repo + plaintext, token_hash = generate_token() + row = repo.rotate( + token_id, + user_id=user.id, + token_hash=token_hash, + token_hint=token_hint(plaintext), + ) + if row is None: + existing = repo.get_for_user(token_id, user_id=user.id) + if existing is not None and existing.revoked_at: + raise OctopError( + ErrorCode.FORBIDDEN, + f"memory MCP token {token_id!r} was revoked and can no longer be rotated", + status=409, + ) + raise OctopError(ErrorCode.NOT_FOUND, f"memory MCP token {token_id!r} not found") + return TokenCreated(**_to_out(row).model_dump(), token=plaintext) + + +@router.delete( + "/{token_id}", + response_model=TokenRevoked, + summary="Revoke a memory MCP token", + description="Revokes one of the caller's own tokens. Other users' tokens are not found.", +) +def revoke_token( + token_id: str, + user: User = Depends(current_user), + server: OctopServer = Depends(get_server), +) -> TokenRevoked: + assert server.services is not None + repo = server.services.repos.memory_mcp_token_repo + if repo.get_for_user(token_id, user_id=user.id) is None: + raise OctopError(ErrorCode.NOT_FOUND, f"memory MCP token {token_id!r} not found") + return TokenRevoked(revoked=repo.revoke(token_id, user_id=user.id)) diff --git a/src/octop/infra/agents/memory_mcp.py b/src/octop/infra/agents/memory_mcp.py new file mode 100644 index 0000000000..9f5058992d --- /dev/null +++ b/src/octop/infra/agents/memory_mcp.py @@ -0,0 +1,1385 @@ +"""Expose Octop expert memory as an MCP server for external agents. + +External agents (coding agents, bots) read and write one expert's memory over MCP +(Streamable HTTP). The endpoint is a single ``/mcp/memory`` mount; the expert is +selected per request with ``X-Octop-Agent-Id`` and the caller is identified by a +**user-bound token** (``Authorization: Bearer omcp_…``) — never by a header the +client can choose. + +Auth model (owner: Octop users, not a shared instance token): + +* each user creates tokens in the dashboard / ``POST /api/memory-mcp/tokens``; + a token can be limited to a set of experts and is revocable per client + (``name`` is the client label, e.g. ``codex@macbook``); +* only the sha256 hash is stored, and verification is a constant-time compare; +* the caller's Octop user comes from the token, and every request re-checks + that the user may access the selected expert (owner / shared-expert rules), + so a token cannot be pointed at somebody else's expert by editing a header. + +Tool surface (``a`` scope of the review split): + +* everyday, any token: ``memory_search`` / ``memory_get`` / ``memory_save`` / + ``memory_capture``; +* review & ops, **expert owner only**: ``memory_raws`` / ``memory_candidates`` / + ``memory_extract`` / ``memory_promote`` / ``memory_reject`` (the dashboard has + the same operations; exposing them to every external agent would let an agent + promote its own writes). + +Write paths go through the octop-memory application layer so behaviour matches +the in-process tools: ``memory_capture`` -> ``MemoryRuntime.capture`` (privacy +redaction, role/min-length policy, recall-echo guard) and ``memory_save`` -> +``MemoryService.save`` (manual-review scheduler). Captured writes land in the L0 +raw layer and are extracted in the background; extraction **promotes only when +the expert's own extraction config asks for it** — by default external writes +wait in the review queue. + +No background extraction starts a stopped expert: an idle expert has no live +``MemoryService`` (and starting it would spend the user's model budget), so the +capture is recorded and extraction is skipped until the expert runs. +""" + +from __future__ import annotations + +import asyncio +import hashlib +import logging +import os +import threading +import time +from collections.abc import AsyncIterator, Callable +from contextlib import AsyncExitStack, asynccontextmanager, suppress +from contextvars import ContextVar +from typing import Any, get_args + +from mcp.server.fastmcp import FastMCP +from mcp.server.transport_security import TransportSecuritySettings + +from octop.infra.agents.memory.backend import open_memory_kwargs +from octop.infra.agents.memory_tokens import hash_token, token_matches +from octop.infra.server import OctopServer +from octop.infra.users.permissions import user_has_permission + +logger = logging.getLogger(__name__) + +# 当前 MCP HTTP 请求的绑定状态(由 _TokenAuthMiddleware / _AgentRouter 写入, +# 工具读取)。stateless streamable HTTP 下 mcp SDK 不提供 ctx.request_context, +# 故用 contextvar 在 ASGI 中间件与工具之间传递。 +_current_agent_id: ContextVar[str] = ContextVar("octop_mcp_agent_id", default="") +_current_user_id: ContextVar[int | None] = ContextVar("octop_mcp_user_id", default=None) +_current_user_name: ContextVar[str] = ContextVar("octop_mcp_user_name", default="") +_current_token_name: ContextVar[str] = ContextVar("octop_mcp_token_name", default="") +_current_token_scope: ContextVar[list[str] | None] = ContextVar( + "octop_mcp_token_scope", default=None +) +"""Experts a token is limited to, or ``None`` when unrestricted.""" + +_SEARCH_CORPORA: frozenset[str] = frozenset({"all", "memory", "atom", "raw"}) +"""Corpora ``memory_search`` accepts. ``atom``/``raw`` are layer filters over the +recall pipeline; ``all``/``memory`` are the same pipeline without a filter.""" + +_SNIPPET_CHARS = 200 + +_USER_ROLE = "user_message" +_ASSISTANT_ROLE = "assistant_message" + +_EXTRACT_TASKS: set[asyncio.Task[None]] = set() +"""Strong references to background extraction tasks (``asyncio`` only keeps a weak +one, so an unreferenced task may be garbage-collected mid-flight).""" + +_EXTRACT_LOCKS: dict[str, asyncio.Lock] = {} + +_CAPTURE_MAX_EVENTS = 200 +"""(default) per-request event limit for ``memory_capture(events=...)``. + +Clients batch below this size and only advance their transcript offset after a +batch is accepted, so a too-large request is rejected instead of being +silently truncated.""" +with suppress(ValueError): # bad env keeps the default + _CAPTURE_MAX_EVENTS = max( + 1, + min(1000, int(os.environ.get("OCTOP_MEMORY_CAPTURE_MAX_EVENTS") or _CAPTURE_MAX_EVENTS)), + ) + +_TOKEN_TOUCH_INTERVAL_S = 60.0 +"""``last_used_at`` only needs minute-level freshness; writing it per request +turned every MCP call into a DB write. Throttle to one write per token/minute.""" +_TOKEN_TOUCH_AT: dict[str, float] = {} +_TOKEN_TOUCH_GUARD = threading.Lock() + + +def _touch_token(repo: Any, token_id: str) -> None: + """Record token use at most once per ``_TOKEN_TOUCH_INTERVAL_S``.""" + now = time.monotonic() + with _TOKEN_TOUCH_GUARD: + last = _TOKEN_TOUCH_AT.get(token_id) + if last is not None and now - last < _TOKEN_TOUCH_INTERVAL_S: + return + _TOKEN_TOUCH_AT[token_id] = now + repo.touch(token_id) + + +_CAPTURE_LOCKS: dict[tuple[str, str], threading.Lock] = {} +_CAPTURE_LOCKS_GUARD = threading.Lock() + + +def _capture_lock(agent_id: str, session_id: str) -> threading.Lock: + """Serialize dedupe+write for one (expert, session) so retries cannot race.""" + with _CAPTURE_LOCKS_GUARD: + return _CAPTURE_LOCKS.setdefault((agent_id, session_id), threading.Lock()) + + +def _event_dedupe_key(payload: dict[str, Any] | None, event: dict[str, Any]) -> str: + """Stable per-event id scoped by caller/session/expert (checked by caller). + + Prefers the client's parser ``src_key``; falls back to a content hash so + older clients still get retry idempotency. + """ + src_key = str((payload or {}).get("src_key") or "").strip() + if src_key: + return f"src:{src_key}" + digest = hashlib.sha256() + digest.update(str(event.get("event_type") or "").encode("utf-8", "replace")) + digest.update(b"\x00") + digest.update(str(event.get("content") or "").encode("utf-8", "replace")) + digest.update(b"\x00") + digest.update(str(event.get("timestamp_iso") or "").encode("utf-8", "replace")) + return f"hash:{digest.hexdigest()}" + + +def _raw_dedupe_key(raw: Any) -> str: + """Dedupe key of an already-stored L0 event (same rules as the writer).""" + payload = raw.payload if isinstance(getattr(raw, "payload", None), dict) else {} + stored = str(payload.get("octop_event_key") or "").strip() + if stored: + return stored + return _event_dedupe_key( + payload, + { + "event_type": raw.event_type, + "content": raw.content, + "timestamp_iso": raw.timestamp.isoformat() if raw.timestamp else "", + }, + ) + + +"""One lock per expert: extraction must never run twice in parallel for the same +expert (the harness memory middleware may extract the same session concurrently).""" + + +def _resolve_agent_scope(server: OctopServer, agent_id: str) -> tuple[Any, dict[str, Any]]: + """The agent's workspace directory + its parsed ``config_json``.""" + services = server.services + assert services is not None, "server.services required for memory backend" + runtime = getattr(server, "app_runtime", None) + registry = getattr(runtime, "agent_registry", None) if runtime is not None else None + if registry is not None and hasattr(registry, "resolve_workspace_dir"): + workspace = registry.resolve_workspace_dir(agent_id) + else: + paths = getattr(server, "paths", None) or services.paths + workspace = paths.ensure_agent_workspace(agent_id) + + row = services.agent_repo.get(agent_id) + cfg: dict[str, Any] = {} + if row is not None and row.config_json: + import json # noqa: PLC0415 + + try: + parsed = json.loads(row.config_json) + if isinstance(parsed, dict): + cfg = parsed + except json.JSONDecodeError: + cfg = {} + return workspace, cfg + + +def _open_memory(server: OctopServer, agent_id: str) -> Any: + """Open the agent's ``Memory`` instance (sqlite by default, postgres opt-in).""" + from octop_memory.core import Memory # noqa: PLC0415 + + services = server.services + assert services is not None, "server.services required for memory backend" + workspace, cfg = _resolve_agent_scope(server, agent_id) + + ns, backend, backend_config = open_memory_kwargs( + agent_id=agent_id, + cfg=cfg, + octop_config=services.config, + workspace_dir=workspace, + ) + return Memory(namespace=ns, backend=backend, backend_config=backend_config) + + +def _memory_runtime(server: OctopServer, agent_id: str) -> Any: + """Capture/search runtime for this expert. + + Prefers the live ``MemoryService`` runtime so the expert's own capture / + privacy config applies; falls back to a default-configured runtime over the + on-disk memory when the expert is not loaded (redaction is on by default). + """ + from octop_memory.application.runtime import MemoryRuntime # noqa: PLC0415 + + runtime = getattr(server, "app_runtime", None) + registry = getattr(runtime, "agent_registry", None) if runtime is not None else None + service = _live_memory_service(registry, agent_id) if registry is not None else None + service_runtime = getattr(service, "_runtime", None) if service is not None else None + if service_runtime is not None: + return service_runtime + return MemoryRuntime(_open_memory(server, agent_id)) + + +def _dashboard_bridge(memory: Any) -> Any: + """Open the harness-memory JSON-RPC bridge over ``memory``. + + The same adapter the memory panel reaches through + ``api/common/memory_client.call_memory_rpc``, so the MCP and the dashboard + can never drift apart on candidate review semantics. + """ + from octop_memory.adapters.bridge.handlers import Bridge # noqa: PLC0415 + + return Bridge(memory) + + +def _bridge_rpc(bridge: Any, method: str, params: dict[str, Any]) -> dict[str, Any]: + """Call one dashboard RPC and return its result, raising ``ValueError`` on error.""" + + def _invoke() -> dict[str, Any]: + response = bridge.handle({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}) + error = response.get("error") + if error: + raise ValueError(error.get("message") or f"memory rpc {method!r} failed") + return response.get("result") or {} + + return _invoke() + + +def _snippet(text: str) -> str: + """Cap a raw event body so ``memory_search`` hits stay small.""" + body = (text or "").strip() + return body if len(body) <= _SNIPPET_CHARS else body[: _SNIPPET_CHARS - 1].rstrip() + "…" + + +def _lookup_raw_users(memory: Any, hits: list[dict[str, Any]]) -> dict[str, str]: + """``{raw event id: user}`` for the raw hits — the raw layer carries the sender.""" + ids = [ + str(hit.get("source_id")) + for hit in hits + if hit.get("layer") == "raw" and hit.get("source_id") + ] + if not ids: + return {} + try: + events = memory.get_raw_events_by_ids(list(dict.fromkeys(ids))) + except Exception: # noqa: BLE001 - attribution must never break search + logger.warning("memory_search: raw attribution lookup failed", exc_info=True) + return {} + return {str(event.id): str(event.user or "") for event in events} + + +def _prefer_personal(memory: Any, hits: list[dict[str, Any]], caller: str) -> list[dict[str, Any]]: + """Stable-partition hits: *caller*'s first, then everyone else's. + + A preference, not a filter — memory is team-shared. Atoms/pages carry no + sender column (external writes no longer stamp a name into the body), so only + raw hits can be marked personal. + """ + raw_users = _lookup_raw_users(memory, hits) + mine: list[dict[str, Any]] = [] + rest: list[dict[str, Any]] = [] + for hit in hits: + personal = ( + hit.get("layer") == "raw" and raw_users.get(str(hit.get("source_id")), "") == caller + ) + hit["personal"] = personal + if hit.get("layer") == "raw" and str(hit.get("source_id")) in raw_users: + hit["user"] = raw_users[str(hit.get("source_id"))] or None + (mine if personal else rest).append(hit) + return [*mine, *rest] + + +def _prefer_personal_events(events: list[Any], caller: str) -> list[Any]: + """Same preference for raw events (``corpus=raw``): own rows first, stable order.""" + mine = [event for event in events if str(getattr(event, "user", "") or "") == caller] + rest = [event for event in events if str(getattr(event, "user", "") or "") != caller] + return [*mine, *rest] + + +def _pipeline_hits( + memory: Any, + query: str, + max_results: int, + *, + atom_only: bool, + caller: str = "", +) -> list[dict[str, Any]]: + """Run the in-process multi-source search and return its path-carrying hits.""" + from octop_memory.application.runtime import MemoryRuntime # noqa: PLC0415 + + runtime = MemoryRuntime(memory) + result = runtime.memory_search( + { + "query": query, + "maxResults": max_results * 4 if (atom_only or caller) else max_results, + "corpus": "memory", + } + ) + hits = list(result.get("hits") or []) + if atom_only: + hits = [hit for hit in hits if hit.get("layer") == "atom"] + if caller: + hits = _prefer_personal(memory, hits, caller) + return hits[:max_results] + + +def _caller_name() -> str: + """Octop user name resolved from this request's token (never a client header).""" + return _current_user_name.get() or f"user:{_current_user_id.get()}" + + +def _agent_row(server: OctopServer) -> Any: + """The agent row bound to this request (validated by ``_AgentRouter``).""" + services = server.services + assert services is not None, "server.services required for memory MCP" + row = services.agent_repo.get(_current_agent_id.get()) + if row is None: + raise RuntimeError("X-Octop-Agent-Id header not bound to a known expert") + return row + + +def _assert_expert_owner(server: OctopServer) -> None: + """Review/ops tools are expert-owner (or admin) only.""" + row = _agent_row(server) + user_id = _current_user_id.get() + if _is_admin(server, user_id): + return + if row.user_id is None or row.user_id != user_id: + raise PermissionError( + "this tool is limited to the expert owner; external agents may use " + "memory_search / memory_get / memory_save / memory_capture" + ) + + +def _is_admin(server: OctopServer, user_id: int | None) -> bool: + user = _user_of(server, user_id) + return bool(getattr(user, "is_admin", False)) + + +def _user_of(server: OctopServer, user_id: int | None) -> Any: + if user_id is None: + return None + manager = getattr(server, "user_manager", None) + if manager is None: + return None + try: + return manager.get_by_id(user_id) + except Exception: # noqa: BLE001 - auth failures surface as "unknown user" + return None + + +def _user_may_access_agent(server: OctopServer, row: Any, user: Any) -> bool: + """Owner / shared-expert visibility check (same helper as the HTTP routers).""" + from octop.infra.users.access import user_may_access_agent # noqa: PLC0415 + + services = server.services + repos = getattr(services, "repos", None) if services is not None else None + return bool(user_may_access_agent(row, user, repos=repos)) + + +def build_memory_mcp(server: OctopServer) -> FastMCP: + """Build the shared memory MCP app (expert bound per request, not per build).""" + mcp = FastMCP( + "octop-memory", + # Stateless streamable HTTP: every request gets a fresh transport, no + # Mcp-Session-Id tracking, so a server restart cannot orphan client + # sessions with -32600 "Session not found". + stateless_http=True, + # Octop runs behind a reverse proxy (Host is the public domain), so the + # mcp SDK's localhost DNS-rebinding protection does not apply. + transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False), + ) + # Collapse the streamable-HTTP path to "/" so the endpoint is exactly + # /mcp/memory (the default "/mcp" would make it /mcp/memory/mcp). + mcp.settings.streamable_http_path = "/" + + def _agent_id() -> str: + agent_id = _current_agent_id.get() + if not agent_id: + raise RuntimeError("X-Octop-Agent-Id header not bound to this request") + return agent_id + + # ─── everyday tools (any user token scoped to the expert) ─────────────── + + @mcp.tool() + async def memory_search( + query: str, + max_results: int = 5, + corpus: str = "all", + ) -> dict[str, Any]: + """**检索记忆(读入口)**:全文检索专家记忆,返回带虚拟路径的命中。 + + 每条命中带 ``path``,交给 ``memory_get`` 读全文;只想把背景拉进上下文就 + 用 ``snippet``,要原话/证据用 ``memory_raws``(仅专家所有者)。 + + Args: + query: 自然语言问题/关键词(中文做 n-gram 分词)。 + max_results: 最多返回命中数,默认 5。 + corpus: ``all``(默认,原子优先、原始事件兜底)/ ``memory`` / + ``atom``(只要长期记忆)/ ``raw``(只要原始事件,适合刚 capture + 还没提炼的内容)。 + """ + corpus_value = (corpus or "all").strip().lower() + if corpus_value not in _SEARCH_CORPORA: + raise ValueError( + f"invalid corpus {corpus!r}; expected one of {sorted(_SEARCH_CORPORA)}" + ) + caller = _caller_name() + + def _run() -> dict[str, Any]: + memory = _open_memory(server, _agent_id()) + if corpus_value == "raw": + from octop_memory.application.path_projection import ( # noqa: PLC0415 + raw_to_path, + ) + + events = list( + memory.search_raw(query, limit=max_results * 4 if caller else max_results) + ) + if caller: + events = _prefer_personal_events(events, caller) + hits = [ + { + "path": raw_to_path(event), + "layer": "raw", + "snippet": _snippet(event.content), + "occurred_at": event.timestamp.isoformat(), + "source_id": event.id, + "user": str(event.user or "") or None, + "personal": str(event.user or "") == caller, + } + for event in events[:max_results] + ] + else: + hits = _pipeline_hits( + memory, + query, + max_results, + atom_only=corpus_value == "atom", + caller=caller, + ) + return { + "marker": "[octop memory search]", + "hits": hits, + "total": len(hits), + "corpus": corpus_value, + "caller": caller, + "personal_hits": sum(1 for hit in hits if hit.get("personal")), + "hint": ( + "每条命中自带 path,可交给 memory_get(path) 读全文;" + "命中按「本次调用者相关」优先排序,团队共享内容不过滤" + ), + } + + return await asyncio.to_thread(_run) + + @mcp.tool() + async def memory_get( + path: str, + start: int | None = None, + lines: int | None = None, + ) -> dict[str, Any]: + """**读取记忆全文**:把 ``memory_search`` 命中的虚拟路径解析成 markdown。 + + 支持 ``atom/.md`` / ``page/.md`` / ``raw//.md``; + 长内容用 ``start`` / ``lines`` 分页。 + + Args: + path: 虚拟路径,取自 ``memory_search`` 的 ``hits[].path``。 + start: 可选起始行号(1-based)。 + lines: 可选返回行数。 + """ + from octop_memory.application.runtime import MemoryRuntime # noqa: PLC0415 + + def _run() -> dict[str, Any]: + params: dict[str, Any] = {"path": path} + if start is not None: + params["from"] = start + if lines is not None: + params["lines"] = lines + try: + result = MemoryRuntime(_open_memory(server, _agent_id())).memory_get(params) + except Exception as exc: # stale / mistyped path from a previous call + return { + "path": path, + "error": f"{exc.__class__.__name__}: {exc}", + "hint": ( + "path 形如 atom/.md / page/.md / " + "raw//.md" + ), + } + return { + "marker": "[octop memory get]", + "path": result.get("path", path), + "kind": result.get("kind"), + "content": result.get("excerpt") or "", + "total_lines": result.get("total_lines"), + "from_line": result.get("from_line"), + "to_line": result.get("to_line"), + "truncated": result.get("truncated"), + "metadata": result.get("metadata") or {}, + } + + return await asyncio.to_thread(_run) + + @mcp.tool() + async def memory_save( + content: str, + source: str, + topic: str | None = None, + supersedes: str | None = None, + ) -> dict[str, Any]: + """**直接保存事实**:把一条已知事实写入长期记忆(跳过提炼,立即可召回)。 + + 用于明确、需长期记住的事实(用户偏好、项目约定)。日常对话内容请用 + ``memory_capture`` 交给提炼管线。 + + 旧事实过时了就用 ``supersedes`` 传旧记忆 id:旧记忆标记 deprecated,新事实 + 立即生效。调用者身份由 token 决定,写进 ``metadata.caller``,不再拼进正文。 + + Args: + content: 要记住(或用来替代旧事实)的内容。 + source: 谁记录的(如 ``coding-agent``),用于追溯。 + topic: 可选主题标签。 + supersedes: 可选——被这条新事实取代的旧记忆 id。 + """ + caller = _caller_name() + agent_id = _agent_id() + service = _require_live_service(server, agent_id) + + def _run() -> dict[str, Any]: + metadata: dict[str, Any] = { + "source": source, + "source_host": source, + "caller": caller, + } + deprecated: bool | None = None + memory = getattr(service, "memory", None) + if supersedes: + if memory is None: + raise RuntimeError("memory backend unavailable for supersedes") + metadata["supersedes"] = supersedes + node = service.save(content, topic=topic, metadata=metadata) + # Only retire the old fact after the replacement is safely stored: if + # ``save`` fails the previous fact must stay active. + if supersedes and memory is not None: + try: + deprecated = memory.deprecate_atom( + supersedes, actor="user", note="superseded by memory_save" + ) + except Exception: # noqa: BLE001 - new fact exists; do not fail the call + logger.warning("memory_save: deprecate_atom failed for %s", supersedes, exc_info=True) + deprecated = False + result: dict[str, Any] = { + "node_id": node.id, + "content": node.content, + "source": source, + "caller": caller, + } + if supersedes: + result["deprecated"] = deprecated + result["superseded_atom_id"] = supersedes + return result + + return await asyncio.to_thread(_run) + + @mcp.tool() + async def memory_capture( + content: str = "", + source: str = "", + session_id: str | None = None, + assistant: str | None = None, + thread_id: str | None = None, + dry_run: bool = False, + extract: bool = True, + events: list[dict[str, Any]] | None = None, + ) -> dict[str, Any]: + """**写入原始事件(L0)**:一轮对话或一段记录,交给提炼流水线。 + + ``content`` 是用户侧/事实侧内容,``assistant`` 是助手回复;两者落在同一批 + 事件里,提取器才能判断"助手建议是否被用户接受"。只记助手结论时 ``content`` + 留空字符串。 + + 走 octop-memory 的 capture 应用层:敏感信息自动脱敏、过短/回声内容按策略丢弃。 + 写入后立即能用 ``memory_search(corpus="raw")`` 查到,提炼成长期记忆后才回到常规 + 检索。默认**不自动晋升**:外部写入先进入审核队列,由专家所有者审核。 + + 调用者身份由 token 决定并写进事件 metadata(``caller`` / ``source_host``); + **不要**再把名字写进正文。 + + Args: + content: 用户侧内容(或一条提炼过的事实);只记助手结论时留空。 + 提供 ``events`` 时可以整段省略。 + source: 谁记录的(如 ``claude-code`` / ``codex``),同时作为 L0 的 host。 + session_id: 可选会话 id;缺省派生 ``ext:{source}:{caller}``,同一段工作 + 请保持稳定。 + assistant: 助手侧回复(可为空)。 + thread_id: 可选线程 id,透传给 L0。 + dry_run: 只解析不写入;返回将要写入的事件。 + extract: 写入后是否在后台触发提炼(默认 True);专家停止时不会自动启动。 + events: 已由客户端解析好的事件列表(`event_type` / `content`,可选 + `payload` / `timestamp_iso`);提供时跳过服务端解析,直接走 + `MemoryRuntime.capture`(脱敏、回声保护、长度限制照常生效)。 + """ + caller = _caller_name() + agent_id = _agent_id() + + def _run() -> dict[str, Any]: + # ---- pre-parsed events (client-side parsers): straight to the runtime + if events is not None: + if len(events) > _CAPTURE_MAX_EVENTS: + raise ValueError( + f"[batch_too_large] events={len(events)} limit={_CAPTURE_MAX_EVENTS}; " + "send smaller batches and advance the client offset per accepted batch" + ) + payload: dict[str, Any] = { + "source": source, + "source_host": _current_token_name.get() or source, + "caller": caller, + } + normalized: list[dict[str, Any]] = [] + seen_keys: set[str] = set() + for item in events: + if not isinstance(item, dict): + continue + body = item.get("content") + if not isinstance(body, str) or not body.strip(): + continue + event: dict[str, Any] = { + "event_type": str(item.get("event_type") or _USER_ROLE), + "content": body, + "payload": {**(item.get("payload") or {}), **payload}, + } + timestamp_iso = item.get("timestamp_iso") + if isinstance(timestamp_iso, str) and timestamp_iso: + event["timestamp_iso"] = timestamp_iso + key = _event_dedupe_key(event["payload"], event) + if key in seen_keys: + continue + seen_keys.add(key) + event["payload"]["octop_event_key"] = key + normalized.append(event) + if not normalized: + raise ValueError("events is empty after dropping blank entries") + effective_session = session_id or f"ext:{source or 'mcp'}:{caller}" + if dry_run: + return { + "marker": "[octop memory capture]", + "recorded": False, + "dry_run": True, + "session_id": effective_session, + "limit": _CAPTURE_MAX_EVENTS, + "events": [ + { + "event_type": e["event_type"], + "content": e["content"], + "caller": caller, + } + for e in normalized + ], + "note": "dry run: parsed only, nothing written", + } + # Retry idempotency: scope is (expert via token, caller, session); + # ``src_key`` from the client is only trusted inside that scope. + memory = _open_memory(server, agent_id) + with _capture_lock(agent_id, effective_session): + known = { + _raw_dedupe_key(raw) + for raw in memory.list_raw( + session_id=effective_session, user=caller, limit=5000 + ) + } + fresh = [ + event + for event in normalized + if event["payload"]["octop_event_key"] not in known + ] + duplicates = len(normalized) - len(fresh) + if not fresh: + return { + "marker": "[octop memory capture]", + "recorded": False, + "session_id": effective_session, + "source": source, + "caller": caller, + "accepted": 0, + "skipped_duplicates": duplicates, + "note": "all events already recorded for this session; retry is idempotent", + } + result = _memory_runtime(server, agent_id).capture( + { + "session_id": effective_session, + "thread_id": thread_id, + "user": caller, + "host": source or "mcp-external", + "events": fresh, + } + ) + accepted = int(result.get("accepted") or 0) + return { + "marker": "[octop memory capture]", + "recorded": accepted > 0, + "session_id": effective_session, + "source": source, + "caller": caller, + "accepted": accepted, + "skipped_duplicates": duplicates, + "limit": _CAPTURE_MAX_EVENTS, + "skipped": { + key.removeprefix("skipped_"): value + for key, value in result.items() + if key.startswith("skipped_") and value + }, + "note": "client-parsed events recorded through MemoryRuntime.capture", + } + pending: list[dict[str, Any]] = [] + # ``source`` is self-reported by the caller; the token name is the + # server-known client identity, so prefer it for provenance. + source_host = _current_token_name.get() or source + payload = {"source": source, "source_host": source_host, "caller": caller} + if content.strip(): + pending.append({"event_type": _USER_ROLE, "content": content, "payload": payload}) + if assistant: + pending.append( + {"event_type": _ASSISTANT_ROLE, "content": assistant, "payload": payload} + ) + if not pending: + raise ValueError("content and assistant are both empty; nothing to record") + + effective_session = session_id or f"ext:{source or 'mcp'}:{caller}" + if dry_run: + return { + "marker": "[octop memory capture]", + "recorded": False, + "dry_run": True, + "session_id": effective_session, + "events": [ + { + "event_type": event["event_type"], + "content": event["content"], + "caller": caller, + } + for event in pending + ], + "note": "dry run: parsed only, nothing written", + } + + runtime = _memory_runtime(server, agent_id) + result = runtime.capture( + { + "session_id": effective_session, + "thread_id": thread_id, + "user": caller, + "host": source or "mcp-external", + "events": pending, + } + ) + accepted = int(result.get("accepted") or 0) + return { + "marker": "[octop memory capture]", + "recorded": accepted > 0, + "session_id": effective_session, + "source": source, + "caller": caller, + "accepted": accepted, + "skipped": { + key.removeprefix("skipped_"): value + for key, value in result.items() + if key.startswith("skipped_") and value + }, + "note": ( + "raw (L0) events recorded; visible now via memory_search(corpus=raw), " + "promoted to long-term memory only after review/提炼" + ), + } + + result = await asyncio.to_thread(_run) + if extract and not dry_run and result.get("recorded"): + result["extract_scheduled"] = _schedule_extract( + server, + agent_id, + str(result["session_id"]), + promote=_expert_extract_promote(server, agent_id), + ) + return result + + # ─── review & ops tools (expert owner only) ───────────────────────────── + + @mcp.tool() + async def memory_raws( + query: str | None = None, + session_id: str | None = None, + host: str | None = None, + user: str | None = None, + limit: int = 50, + ) -> dict[str, Any]: + """**查原始事件(仅专家所有者)**:FTS 搜索或结构化过滤 L0 原始事件。 + + Args: + query: FTS 关键词(可选)。 + session_id: 按会话过滤。 + host: 按记录主机过滤(如 ``claude-code``)。 + user: 按调用者过滤。 + limit: 最多返回条数,默认 50。 + """ + _assert_expert_owner(server) + + def _run() -> dict[str, Any]: + memory = _open_memory(server, _agent_id()) + events = ( + memory.search_raw(query, limit=limit) + if query + else memory.list_raw( + session_id=session_id, + host=host, + user=user or _caller_name(), + limit=limit, + ) + ) + return { + "events": [ + { + "event_id": e.id, + "timestamp": e.timestamp.isoformat(), + "session_id": e.session_id, + "user": e.user, + "event_type": e.event_type, + "source": (e.payload or {}).get("source") if e.payload else None, + "content": e.content, + } + for e in events + ], + "count": len(events), + } + + return await asyncio.to_thread(_run) + + @mcp.tool() + async def memory_candidates( + status: str | None = None, + session_id: str | None = None, + limit: int = 50, + ) -> dict[str, Any]: + """**查候选记忆(仅专家所有者)**:列出 L1 候选(默认 pending 队列)。 + + Args: + status: pending / promoted / rejected / needs_review / conflict。 + session_id: 按来源会话过滤。 + limit: 最多返回条数,默认 50。 + """ + _assert_expert_owner(server) + from octop_memory.core import CandidateStatus # noqa: PLC0415 + + status_value: str | None = None + if status: + allowed = set(get_args(CandidateStatus)) + if status not in allowed: + raise ValueError( + f"invalid candidate status {status!r}; expected one of {sorted(allowed)}" + ) + status_value = status + + def _run() -> dict[str, Any]: + candidates = _open_memory(server, _agent_id()).list_candidates( + status=status_value, + session_id=session_id, + limit=limit, + ) + return { + "candidates": [ + { + "candidate_id": c.id, + "status": c.status.value if hasattr(c.status, "value") else str(c.status), + "candidate_type": getattr(c, "candidate_type", None), + "assertion": getattr(c, "assertion", None), + "session_id": getattr(c, "session_id", None), + "confidence": getattr(c, "confidence", None), + } + for c in candidates + ], + "count": len(candidates), + } + + return await asyncio.to_thread(_run) + + @mcp.tool() + async def memory_extract( + session_id: str | None = None, + promote: bool | None = None, + ) -> dict[str, Any]: + """**手动触发提炼(仅专家所有者)**:把 L0 事件提炼为候选。 + + 专家未运行时直接返回错误(不会为了提炼而启动专家,避免意外模型开销)。 + + Args: + session_id: 只提炼该会话;缺省为 ``manual``。 + promote: 是否对候选执行晋升检查;缺省跟随专家自己的提炼配置(外部写入 + 默认进入审核队列)。 + """ + _assert_expert_owner(server) + agent_id = _agent_id() + service = _require_live_service(server, agent_id) + effective_session = session_id or "manual" + effective_promote = ( + _expert_extract_promote(server, agent_id) if promote is None else bool(promote) + ) + + def _run() -> dict[str, Any]: + result = service.extract( + effective_session, + incremental=True, + promote=effective_promote, + regen_pages=False, + ) + if not isinstance(result, dict): + return { + "session_id": effective_session, + "candidates": 0, + "promoted": 0, + "promote": effective_promote, + } + promotion = result.get("promotion") + return { + "session_id": effective_session, + "events_considered": result.get("events_considered", 0), + "candidates": result.get("candidates", 0), + "promoted": promotion.get("promoted", 0) if isinstance(promotion, dict) else 0, + "promote": effective_promote, + "error": result.get("failure_reason"), + "promotion": promotion, + } + + return await asyncio.to_thread(_run) + + @mcp.tool() + async def memory_promote(candidate_ids: list[str]) -> dict[str, Any]: + """**采纳候选(仅专家所有者)**:与记忆面板「采纳」同一套实现。 + + Args: + candidate_ids: 要采纳的候选 id 列表(来自 ``memory_candidates``)。 + """ + _assert_expert_owner(server) + bridge = _dashboard_bridge(_open_memory(server, _agent_id())) + + def _run() -> dict[str, Any]: + totals = dict.fromkeys( + ("promoted", "merged", "conflicts", "needs_review", "dropped", "llm_calls"), + 0, + ) + candidates: list[dict[str, Any]] = [] + errors: list[dict[str, Any]] = [] + for candidate_id in candidate_ids: + try: + detail = _bridge_rpc( + bridge, "promote_candidate", {"candidate_id": candidate_id} + ) + except Exception as exc: # noqa: BLE001 - 逐条隔离,错误原样回给调用方 + errors.append({"candidate_id": candidate_id, "error": str(exc)}) + continue + candidates.append({"candidate_id": candidate_id, **detail}) + for key in totals: + totals[key] += int(detail.get(key) or 0) + return {**totals, "candidates": candidates, "errors": errors} + + return await asyncio.to_thread(_run) + + @mcp.tool() + async def memory_reject( + candidate_id: str, + reason: str = "rejected by external caller", + actor: str | None = None, + ) -> dict[str, Any]: + """**忽略候选(仅专家所有者)**:与记忆面板「忽略」同一套实现。 + + Args: + candidate_id: 候选 id。 + reason: 忽略原因(写入 journal note)。 + actor: 决策者,缺省 ``user``;可选 ``auto`` / ``rule``。 + """ + _assert_expert_owner(server) + params: dict[str, Any] = {"candidate_id": candidate_id} + if reason: + params["reason"] = reason + if actor: + params["actor"] = actor + + def _run() -> dict[str, Any]: + result = _bridge_rpc( + _dashboard_bridge(_open_memory(server, _agent_id())), + "reject_candidate", + params, + ) + return {"ok": True, **result} + + return await asyncio.to_thread(_run) + + return mcp + + +def _memory_service_of(agent: Any) -> Any | None: + """``MemoryService`` on a live harness agent, or ``None`` when memory is off.""" + runtime = getattr(agent, "_memory_runtime", None) + return getattr(runtime, "service", None) if runtime is not None else None + + +def _live_memory_service(registry: Any, agent_id: str) -> Any | None: + """Return the in-process ``MemoryService`` when the expert is already loaded.""" + get_agent = getattr(registry, "get_agent", None) + if not callable(get_agent): + return None + try: + agent = get_agent(agent_id) + except Exception: # noqa: BLE001 — not running / not found / harness down + return None + return _memory_service_of(agent) + + +def _require_live_service(server: OctopServer, agent_id: str) -> Any: + """The expert's live ``MemoryService``; never starts a stopped expert. + + Starting an expert spends the owner's model budget, so the MCP layer refuses + instead (the review asked not to auto-start experts). + """ + runtime = getattr(server, "app_runtime", None) + registry = getattr(runtime, "agent_registry", None) if runtime is not None else None + service = _live_memory_service(registry, agent_id) if registry is not None else None + if service is None: + raise RuntimeError( + f"expert {agent_id!r} is not running, so its MemoryService is unavailable; " + "start the expert (or use memory_capture, which writes L0 without it)" + ) + return service + + +def _expert_extract_promote(server: OctopServer, agent_id: str) -> bool: + """Whether extraction should promote, following the expert's **explicit** config. + + ``_extraction_cfg()`` merges library defaults (octop-memory 1.0.4 defaults + ``promote=True``), so reading it would silently auto-promote external writes. + External capture stays review-only unless the expert itself set ``promote``. + """ + runtime = getattr(server, "app_runtime", None) + registry = getattr(runtime, "agent_registry", None) if runtime is not None else None + service = _live_memory_service(registry, agent_id) if registry is not None else None + service_runtime = getattr(service, "_runtime", None) if service is not None else None + config = getattr(service_runtime, "_config", None) + extraction = getattr(config, "extraction", None) + if isinstance(extraction, dict): + return bool(extraction.get("promote", False)) if "promote" in extraction else False + promote = getattr(extraction, "promote", None) if extraction is not None else None + return bool(promote) if promote is not None else False + + +def _schedule_extract( + server: OctopServer, + agent_id: str, + session_id: str, + *, + promote: bool, +) -> bool: + """Schedule a background extract (serialized per expert, never auto-starts).""" + runtime = getattr(server, "app_runtime", None) + registry = getattr(runtime, "agent_registry", None) if runtime is not None else None + if registry is None: + return False + service = _live_memory_service(registry, agent_id) + if service is None: + logger.info( + "memory extract skipped for agent %s session %s: expert not running", + agent_id, + session_id, + ) + return False + + async def _run() -> None: + lock = _EXTRACT_LOCKS.setdefault(agent_id, asyncio.Lock()) + async with lock: + try: + result = await asyncio.to_thread( + service.extract, + session_id, + incremental=True, + promote=promote, + regen_pages=True, + ) + except Exception: # noqa: BLE001 - background work must not crash the loop + logger.warning( + "memory extract failed for agent %s session %s", + agent_id, + session_id, + exc_info=True, + ) + return + reason = _extract_failure_reason(result) + if reason: + logger.warning( + "memory extract failed for agent %s session %s: %s", + agent_id, + session_id, + reason, + ) + + try: + task = asyncio.get_running_loop().create_task(_run()) + except RuntimeError: # no running loop (sync test call path) + logger.warning("memory extract not scheduled for agent %s: no running loop", agent_id) + return False + _EXTRACT_TASKS.add(task) + task.add_done_callback(_EXTRACT_TASKS.discard) + return True + + +def _extract_failure_reason(result: Any) -> str | None: + """Return the failure reason reported by ``MemoryService.extract``, if any.""" + if not isinstance(result, dict): + return None + for key in ("failure_reason", "error"): + value = result.get(key) + if isinstance(value, str) and value.strip(): + return value.strip() + return None + + +# ─── ASGI auth: user token -> user, then expert binding + access check ─────── + + +async def _send_json(send: Any, status: int, body: dict[str, Any]) -> None: + import json # noqa: PLC0415 + + payload = json.dumps(body, ensure_ascii=False).encode("utf-8") + await send( + { + "type": "http.response.start", + "status": status, + "headers": [ + (b"content-type", b"application/json; charset=utf-8"), + (b"content-length", str(len(payload)).encode("ascii")), + ], + } + ) + await send({"type": "http.response.body", "body": payload}) + + +def _headers(scope: dict[str, Any]) -> dict[str, str]: + return {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope.get("headers", [])} + + +class _TokenAuthMiddleware: + """Resolve the caller from a user-bound bearer token. + + The token is looked up by its sha256 hash and compared in constant time; the + caller identity is the token's owner. ``X-Octop-User-Id`` is deliberately + ignored — a client cannot name somebody else. + """ + + def __init__(self, app: Any, server: OctopServer) -> None: + self._app = app + self._server = server + + async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None: + if scope.get("type") != "http": + await self._app(scope, receive, send) + return + + headers = _headers(scope) + auth = headers.get("authorization", "") + provided = auth[7:].strip() if auth.startswith("Bearer ") else "" + if not provided: + provided = headers.get("x-octop-memory-token", "").strip() + if not provided: + await _send_json(send, 401, {"error": "missing bearer token"}) + return + + services = self._server.services + repo = getattr(getattr(services, "repos", None), "memory_mcp_token_repo", None) + if repo is None: + await _send_json(send, 401, {"error": "token store unavailable"}) + return + + digest = hash_token(provided) + row = await asyncio.to_thread(repo.get_by_token_hash, digest) + if row is None or not token_matches(provided, row.token_hash): + await _send_json(send, 401, {"error": "invalid token"}) + return + if row.revoked_at: + await _send_json(send, 401, {"error": "token revoked"}) + return + + user = await asyncio.to_thread(_user_of, self._server, row.user_id) + if user is None: + await _send_json(send, 401, {"error": "token owner not found"}) + return + # Permission may be withdrawn after the token was issued: re-check it per + # request so revoking ``memory`` takes effect for existing tokens at once. + if not user_has_permission(user, "memory"): + await _send_json( + send, + 403, + {"error": "permission required", "permission": "memory"}, + ) + return + + # Clients that identify themselves (``X-Octop-Client``) are counted per + # token and can be refused; a request without the header is never + # counted and never blocked, so existing clients keep working. + client = headers.get("x-octop-client", "").strip()[:64] + if client: + try: + await asyncio.to_thread(repo.record_client, row.token_id, client) + except Exception: # noqa: BLE001 - usage stats must never fail a request + logger.warning( + "memory MCP client stats update failed for token %s", + row.token_id, + exc_info=True, + ) + if client in (row.disabled_clients or []): + await _send_json( + send, + 403, + {"error": "this client is disabled for this token", "client": client}, + ) + return + + user_id_cv = _current_user_id.set(int(row.user_id)) + user_name_cv = _current_user_name.set(str(getattr(user, "username", "") or row.user_id)) + token_name_cv = _current_token_name.set(row.name) + scope_cv = _current_token_scope.set(list(row.expert_ids) if row.expert_ids else None) + try: + await asyncio.to_thread(_touch_token, repo, row.token_id) + await self._app(scope, receive, send) + finally: + _current_token_scope.reset(scope_cv) + _current_token_name.reset(token_name_cv) + _current_user_name.reset(user_name_cv) + _current_user_id.reset(user_id_cv) + + +class _AgentRouter: + """Bind the request to one expert and check the token owner's access to it. + + The expert comes from ``X-Octop-Agent-Id`` when the client sends it. A token + bound to exactly one expert is a 唯一令牌: it names the expert itself, so the + client may omit the header. A token with no ``expert_ids`` and one covering + several experts still needs the header — the request is rejected with 400 + rather than guessed at. + + The expert set is not snapshotted: existence / ``enabled`` / ownership are + re-checked per request, so experts created, shared or disabled after process + start take effect immediately. + """ + + def __init__(self, app: Any, server: OctopServer) -> None: + self._app = app + self._server = server + + async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None: + if scope.get("type") != "http": + await self._app(scope, receive, send) + return + + headers = _headers(scope) + requested_agent_id = headers.get("x-octop-agent-id", "").strip() + token_scope = _current_token_scope.get() + if requested_agent_id: + agent_id = requested_agent_id + elif token_scope is not None and len(token_scope) == 1: + agent_id = token_scope[0] + else: + hint = "either bind the token to a single expert, or send X-Octop-Agent-Id" + body: dict[str, Any] = {"error": hint} + if token_scope is not None: + body["allowed_expert_ids"] = list(token_scope) + await _send_json(send, 400, body) + return + + services = self._server.services + row = services.agent_repo.get(agent_id) if services is not None else None + if row is None or not row.enabled: + await _send_json(send, 404, {"error": "missing or unknown agent_id (X-Octop-Agent-Id)"}) + return + + user = _user_of(self._server, _current_user_id.get()) + if token_scope is not None and agent_id not in token_scope: + await _send_json( + send, + 403, + {"error": "this token is not scoped to that expert", "agent_id": agent_id}, + ) + return + if not _user_may_access_agent(self._server, row, user): + await _send_json( + send, + 403, + {"error": "token owner cannot access that expert", "agent_id": agent_id}, + ) + return + + agent_cv = _current_agent_id.set(agent_id) + try: + await self._app(scope, receive, send) + finally: + _current_agent_id.reset(agent_cv) + + +def _chain_lifespan(previous: Any, managers: list[Any]) -> Callable[[Any], Any]: + """Wrap the host lifespan so MCP session managers run without hiding hooks.""" + + @asynccontextmanager + async def _lifespan(app: Any) -> AsyncIterator[None]: + async with AsyncExitStack() as stack: + for manager in managers: + await stack.enter_async_context(manager.run()) + if previous is not None: + await stack.enter_async_context(previous(app)) + yield + + return _lifespan + + +def _memory_mcp_enabled() -> bool: + """Mount only when ``OCTOP_MEMORY_MCP_ENABLED`` asks for it. + + Token existence no longer flips the mount on: the endpoint appears (or not) + at process start, so an operator enables it once and every token created + afterwards works without a restart. + """ + flag = (os.environ.get("OCTOP_MEMORY_MCP_ENABLED") or "").strip().lower() + return flag in {"1", "true", "yes", "on"} + + +def install_memory_mcp(app: Any, server: OctopServer) -> None: + """Mount ``/mcp/memory`` and keep the host lifespan intact. + + Mounts only when ``OCTOP_MEMORY_MCP_ENABLED`` is on (fail-closed: an + unconfigured instance exposes nothing). The MCP + session managers are chained into the existing FastAPI lifespan instead of + replacing it, so future startup/shutdown hooks keep working. + """ + if not _memory_mcp_enabled(): + return + services = server.services + if services is None: + # Greenfield deferral: /setup binds the database after this app is built. + # Skip the mount instead of failing startup; restart once setup completes. + logger.warning("memory MCP not mounted: server services not ready (finish /setup)") + return + + mcp = build_memory_mcp(server) + # _session_manager is created lazily by streamable_http_app(); read it only + # after building, and drop None entries (stateless mode has none). + streamable_app = mcp.streamable_http_app() + managers = [mgr for mgr in (getattr(mcp, "_session_manager", None),) if mgr is not None] + + app.mount("/mcp/memory", _TokenAuthMiddleware(_AgentRouter(streamable_app, server), server)) + if managers: + app.router.lifespan_context = _chain_lifespan(app.router.lifespan_context, managers) + + +__all__ = ["build_memory_mcp", "install_memory_mcp"] diff --git a/src/octop/infra/agents/memory_tokens.py b/src/octop/infra/agents/memory_tokens.py new file mode 100644 index 0000000000..2ae6bf6dba --- /dev/null +++ b/src/octop/infra/agents/memory_tokens.py @@ -0,0 +1,39 @@ +"""User-level API token helpers for the memory MCP server. + +Shared by the HTTP router that issues tokens and by MCP request +authentication. Only the SHA-256 hex digest is persisted; the plaintext +token is returned once at creation and never stored. +""" + +from __future__ import annotations + +import hashlib +import hmac +import secrets + +TOKEN_PREFIX = "omcp_" + +_TOKEN_BYTES = 32 +_HINT_HEAD = len(TOKEN_PREFIX) + 4 +_HINT_TAIL = 4 + + +def generate_token() -> tuple[str, str]: + """Return ``(plaintext, sha256_hex)`` for a fresh token.""" + plaintext = f"{TOKEN_PREFIX}{secrets.token_urlsafe(_TOKEN_BYTES)}" + return plaintext, hash_token(plaintext) + + +def hash_token(token: str) -> str: + """SHA-256 hex digest of *token* — the only form that is stored.""" + return hashlib.sha256(token.encode("utf-8")).hexdigest() + + +def token_matches(token: str, token_hash: str) -> bool: + """Constant-time check of *token* against a stored digest.""" + return hmac.compare_digest(hash_token(token), token_hash) + + +def token_hint(token: str) -> str: + """Display form with the middle hidden, e.g. ``omcp_abcd…wxyz``.""" + return f"{token[:_HINT_HEAD]}…{token[-_HINT_TAIL:]}" diff --git a/src/octop/infra/db/migrations/026_memory_mcp_tokens.pg.sql b/src/octop/infra/db/migrations/026_memory_mcp_tokens.pg.sql new file mode 100644 index 0000000000..1d6cb40218 --- /dev/null +++ b/src/octop/infra/db/migrations/026_memory_mcp_tokens.pg.sql @@ -0,0 +1,29 @@ +-- Schema v26: user-level API tokens for the memory MCP server. +-- +-- One row per client token. Only the SHA-256 hex digest is stored; the +-- plaintext token is shown once at creation. NULL expert_ids means the token +-- may use every expert its owner can access. +-- +-- disabled_clients is a JSON array of client names ("codex", "cursor", …) the +-- token refuses; NULL/empty allows every client. client_stats is a JSON object +-- of {"": {"first_seen": iso, "last_seen": iso, "count": n}} filled in +-- from the X-Octop-Client header the client sends. + +CREATE TABLE IF NOT EXISTS memory_mcp_tokens ( + id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, + token_id TEXT NOT NULL UNIQUE, + user_id BIGINT NOT NULL REFERENCES users(id) ON DELETE CASCADE, + name TEXT NOT NULL, + expert_ids TEXT, + disabled_clients TEXT, + client_stats TEXT, + token_hash TEXT NOT NULL UNIQUE, + token_hint TEXT NOT NULL, + created_at TEXT NOT NULL, + last_used_at TEXT, + revoked_at TEXT +); + +CREATE INDEX IF NOT EXISTS idx_memory_mcp_tokens_user ON memory_mcp_tokens(user_id); + +UPDATE _schema_version SET version = 26; diff --git a/src/octop/infra/db/migrations/026_memory_mcp_tokens.sql b/src/octop/infra/db/migrations/026_memory_mcp_tokens.sql new file mode 100644 index 0000000000..a7aebdb293 --- /dev/null +++ b/src/octop/infra/db/migrations/026_memory_mcp_tokens.sql @@ -0,0 +1,29 @@ +-- Schema v26: user-level API tokens for the memory MCP server. +-- +-- One row per client token. Only the SHA-256 hex digest is stored; the +-- plaintext token is shown once at creation. NULL expert_ids means the token +-- may use every expert its owner can access. +-- +-- disabled_clients is a JSON array of client names ("codex", "cursor", …) the +-- token refuses; NULL/empty allows every client. client_stats is a JSON object +-- of {"": {"first_seen": iso, "last_seen": iso, "count": n}} filled in +-- from the X-Octop-Client header the client sends. + +CREATE TABLE IF NOT EXISTS memory_mcp_tokens ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + token_id TEXT NOT NULL UNIQUE, + user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE, + name TEXT NOT NULL, + expert_ids TEXT, + disabled_clients TEXT, + client_stats TEXT, + token_hash TEXT NOT NULL UNIQUE, + token_hint TEXT NOT NULL, + created_at TEXT NOT NULL, + last_used_at TEXT, + revoked_at TEXT +); + +CREATE INDEX IF NOT EXISTS idx_memory_mcp_tokens_user ON memory_mcp_tokens(user_id); + +UPDATE _schema_version SET version = 26; diff --git a/src/octop/infra/db/repos/memory_mcp_tokens.py b/src/octop/infra/db/repos/memory_mcp_tokens.py new file mode 100644 index 0000000000..ee3f02cc19 --- /dev/null +++ b/src/octop/infra/db/repos/memory_mcp_tokens.py @@ -0,0 +1,253 @@ +"""Memory MCP API tokens — one row per user-issued client token.""" + +from __future__ import annotations + +import json +from dataclasses import dataclass +from datetime import UTC, datetime +from typing import Any + +from octop.infra.db.pool import DatabasePool +from octop.infra.db.repos._base import DbRow, map_rows + + +def _utc_now_iso() -> str: + return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z") + + +def _dump_expert_ids(expert_ids: list[str] | None) -> str | None: + return None if expert_ids is None else json.dumps(expert_ids) + + +def _load_expert_ids(raw: object) -> list[str] | None: + if raw is None: + return None + text = str(raw) + if not text: + return None + return [str(item) for item in json.loads(text)] + + +def _dump_disabled_clients(clients: list[str] | None) -> str | None: + """``None``/empty means "every client allowed", stored as SQL NULL.""" + return None if not clients else json.dumps(clients) + + +def _load_disabled_clients(raw: object) -> list[str] | None: + if raw is None: + return None + text = str(raw) + if not text: + return None + return [str(item) for item in json.loads(text)] or None + + +def _load_client_stats(raw: object) -> dict[str, dict[str, Any]] | None: + if raw is None: + return None + text = str(raw) + if not text: + return None + return {str(client): dict(stats) for client, stats in json.loads(text).items()} or None + + +@dataclass(frozen=True) +class MemoryMcpTokenRow: + id: int + token_id: str + user_id: int + name: str + expert_ids: list[str] | None + token_hash: str + token_hint: str + created_at: str + last_used_at: str | None + revoked_at: str | None + disabled_clients: list[str] | None = None + client_stats: dict[str, dict[str, Any]] | None = None + + @classmethod + def from_row(cls, r: DbRow) -> MemoryMcpTokenRow: + return cls( + id=int(r["id"]), + token_id=str(r["token_id"]), + user_id=int(r["user_id"]), + name=str(r["name"]), + expert_ids=_load_expert_ids(r["expert_ids"]), + token_hash=str(r["token_hash"]), + token_hint=str(r["token_hint"]), + created_at=str(r["created_at"]), + last_used_at=str(r["last_used_at"]) if r["last_used_at"] is not None else None, + revoked_at=str(r["revoked_at"]) if r["revoked_at"] is not None else None, + disabled_clients=_load_disabled_clients(r["disabled_clients"]), + client_stats=_load_client_stats(r["client_stats"]), + ) + + +class MemoryMcpTokenRepo: + def __init__(self, db: DatabasePool) -> None: + self._db = db + + def create( + self, + *, + user_id: int, + name: str, + expert_ids: list[str] | None, + token_id: str, + token_hash: str, + token_hint: str, + ) -> MemoryMcpTokenRow: + with self._db.transaction() as conn: + conn.execute( + "INSERT INTO memory_mcp_tokens(" + "token_id, user_id, name, expert_ids, token_hash, token_hint, created_at" + ") VALUES (?, ?, ?, ?, ?, ?, ?)", + ( + token_id, + user_id, + name, + _dump_expert_ids(expert_ids), + token_hash, + token_hint, + _utc_now_iso(), + ), + ) + row = self.get_by_token_hash(token_hash) + if row is None: + raise RuntimeError(f"memory MCP token insert failed: {token_id}") + return row + + def list_for_user(self, user_id: int) -> list[MemoryMcpTokenRow]: + with self._db.connect() as conn: + rows = conn.execute( + "SELECT * FROM memory_mcp_tokens WHERE user_id = ? " + "ORDER BY created_at DESC, id DESC", + (user_id,), + ).fetchall() + return map_rows(rows, MemoryMcpTokenRow) + + def get_by_token_hash(self, token_hash: str) -> MemoryMcpTokenRow | None: + """Look up by digest; revoked rows are returned so the caller can reject them.""" + with self._db.connect() as conn: + r = conn.execute( + "SELECT * FROM memory_mcp_tokens WHERE token_hash = ?", + (token_hash,), + ).fetchone() + return MemoryMcpTokenRow.from_row(r) if r else None + + def any_active(self) -> bool: + """True when at least one unrevoked token exists (MCP mount gate).""" + with self._db.connect() as conn: + r = conn.execute( + "SELECT 1 FROM memory_mcp_tokens WHERE revoked_at IS NULL LIMIT 1" + ).fetchone() + return r is not None + + def get_for_user(self, token_id: str, *, user_id: int) -> MemoryMcpTokenRow | None: + with self._db.connect() as conn: + r = conn.execute( + "SELECT * FROM memory_mcp_tokens WHERE token_id = ? AND user_id = ?", + (token_id, user_id), + ).fetchone() + return MemoryMcpTokenRow.from_row(r) if r else None + + def update( + self, + token_id: str, + *, + user_id: int, + name: str, + expert_ids: list[str] | None, + disabled_clients: list[str] | None = None, + ) -> MemoryMcpTokenRow | None: + """Replace one live token's name / expert allow-list / disabled clients. + + ``None`` for ``disabled_clients`` clears the restriction (every client + allowed). ``None`` as the return value means the row is gone or already + revoked — the caller decides whether that is 404 or 409. + """ + with self._db.transaction() as conn: + cursor = conn.execute( + "UPDATE memory_mcp_tokens SET name = ?, expert_ids = ?, disabled_clients = ? " + "WHERE token_id = ? AND user_id = ? AND revoked_at IS NULL", + ( + name, + _dump_expert_ids(expert_ids), + _dump_disabled_clients(disabled_clients), + token_id, + user_id, + ), + ) + if int(cursor.rowcount or 0) == 0: + return None + return self.get_for_user(token_id, user_id=user_id) + + def rotate( + self, + token_id: str, + *, + user_id: int, + token_hash: str, + token_hint: str, + ) -> MemoryMcpTokenRow | None: + """Replace a live token's secret (hash + hint); old plaintext stops working. + + Returns ``None`` when the row is gone, owned by somebody else, or already + revoked — the caller decides whether that is 404 or 409. + """ + with self._db.transaction() as conn: + cursor = conn.execute( + "UPDATE memory_mcp_tokens SET token_hash = ?, token_hint = ?, last_used_at = NULL " + "WHERE token_id = ? AND user_id = ? AND revoked_at IS NULL", + (token_hash, token_hint, token_id, user_id), + ) + if int(cursor.rowcount or 0) <= 0: + return None + row = conn.execute( + "SELECT * FROM memory_mcp_tokens WHERE token_id = ?", (token_id,) + ).fetchone() + return MemoryMcpTokenRow.from_row(row) if row is not None else None + + def revoke(self, token_id: str, *, user_id: int) -> bool: + """Mark the token revoked; ``False`` when it was already revoked.""" + with self._db.transaction() as conn: + cursor = conn.execute( + "UPDATE memory_mcp_tokens SET revoked_at = ? " + "WHERE token_id = ? AND user_id = ? AND revoked_at IS NULL", + (_utc_now_iso(), token_id, user_id), + ) + return int(cursor.rowcount or 0) > 0 + + def touch(self, token_id: str) -> None: + with self._db.transaction() as conn: + conn.execute( + "UPDATE memory_mcp_tokens SET last_used_at = ? WHERE token_id = ?", + (_utc_now_iso(), token_id), + ) + + def record_client(self, token_id: str, client: str, now: str | None = None) -> None: + """Count one request from ``client`` on this token; keep first/last seen. + + A missing or revoked row is a no-op: the caller has already validated + the token, so there is nothing to report. Concurrent requests may lose + an increment (read-modify-write) — acceptable for usage statistics. + """ + with self._db.transaction() as conn: + r = conn.execute( + "SELECT client_stats, revoked_at FROM memory_mcp_tokens WHERE token_id = ?", + (token_id,), + ).fetchone() + if r is None or r["revoked_at"] is not None: + return + stats = _load_client_stats(r["client_stats"]) or {} + seen = now or _utc_now_iso() + entry = dict(stats.get(client) or {}) + entry["first_seen"] = entry.get("first_seen") or seen + entry["last_seen"] = seen + entry["count"] = int(entry.get("count") or 0) + 1 + stats[client] = entry + conn.execute( + "UPDATE memory_mcp_tokens SET client_stats = ? WHERE token_id = ?", + (json.dumps(stats), token_id), + ) diff --git a/src/octop/infra/db/services.py b/src/octop/infra/db/services.py index 3a7e7a6c30..c57405dc86 100644 --- a/src/octop/infra/db/services.py +++ b/src/octop/infra/db/services.py @@ -24,6 +24,7 @@ from octop.infra.db.repos.cron import CronJobRepo from octop.infra.db.repos.invites import InviteRepo from octop.infra.db.repos.knowledge import KnowledgeRepo +from octop.infra.db.repos.memory_mcp_tokens import MemoryMcpTokenRepo from octop.infra.db.repos.proactive_care_config import ProactiveCareConfigRepo from octop.infra.db.repos.profile_avatars import ProfileAvatarRepo from octop.infra.db.repos.providers import ProviderRepo @@ -74,6 +75,7 @@ class RepoBundle: skill_package_repo: SkillPackageRepo published_expert_repo: PublishedExpertRepo knowledge_repo: KnowledgeRepo + memory_mcp_token_repo: MemoryMcpTokenRepo voice_provider_repo: SealedVoiceProviderRepo care_push_repo: CarePushRepo proactive_care_config_repo: ProactiveCareConfigRepo @@ -114,6 +116,7 @@ def from_pool(cls, db: DatabasePool) -> RepoBundle: skill_package_repo=SkillPackageRepo(db), published_expert_repo=PublishedExpertRepo(db), knowledge_repo=KnowledgeRepo(db), + memory_mcp_token_repo=MemoryMcpTokenRepo(db), voice_provider_repo=SealedVoiceProviderRepo(VoiceProviderRepo(db), secret_repo), care_push_repo=CarePushRepo(db), proactive_care_config_repo=ProactiveCareConfigRepo(db), @@ -224,6 +227,10 @@ def published_expert_repo(self) -> PublishedExpertRepo: def knowledge_repo(self) -> KnowledgeRepo: return self.repos.knowledge_repo + @property + def memory_mcp_token_repo(self) -> MemoryMcpTokenRepo: + return self.repos.memory_mcp_token_repo + @property def voice_provider_repo(self) -> SealedVoiceProviderRepo: return self.repos.voice_provider_repo diff --git a/src/octop/infra/users/access.py b/src/octop/infra/users/access.py new file mode 100644 index 0000000000..6a8379deb0 --- /dev/null +++ b/src/octop/infra/users/access.py @@ -0,0 +1,39 @@ +"""Single source of truth for per-user expert visibility. + +Both the HTTP routers and the memory MCP middleware gate access with the same +rule; keeping one implementation means an admin/shared-expert change cannot +silently diverge between the two surfaces. +""" + +from __future__ import annotations + +from typing import Any + + +def agent_is_shared(row: Any) -> bool: + return int(getattr(row, "is_shared", 0) or 0) == 1 + + +def user_owns_agent(row: Any, user: Any) -> bool: + return row.user_id is not None and row.user_id == user.id + + +def user_may_access_agent(row: Any, user: Any, *, repos: Any | None = None) -> bool: + """Owner, admin, or shared expert visible to the user's groups. + + ``repos`` is optional for call sites without the repo bundle: a shared expert + is then treated as visible (the historical HTTP behaviour). + """ + if user is None: + return False + if getattr(user, "is_admin", False): + return True + if user_owns_agent(row, user): + return True + if not agent_is_shared(row): + return False + if repos is None: + return True + from octop.infra.users.groups import expert_visible_to # noqa: PLC0415 + + return bool(expert_visible_to(repos, row, user_id=user.id, is_admin=False)) diff --git a/tests/unit/agents/test_memory_mcp.py b/tests/unit/agents/test_memory_mcp.py new file mode 100644 index 0000000000..9682fd5a5e --- /dev/null +++ b/tests/unit/agents/test_memory_mcp.py @@ -0,0 +1,1199 @@ +"""Unit tests for the expert memory MCP server (infra/agents/memory_mcp). + +Covers the post-review surface: user-bound token auth, per-request expert access +checks, capture through ``MemoryRuntime.capture`` (redaction included), save +through ``MemoryService.save``, owner-only review tools, and the lifespan / +mount rules. +""" + +from __future__ import annotations + +import asyncio +import inspect +import json +from types import SimpleNamespace +from typing import Any + +import pytest + +from octop.infra.agents import memory_mcp as mm + +# ─── fakes ────────────────────────────────────────────────────────────────── + + +class _User: + def __init__( + self, + user_id: int, + username: str, + *, + is_admin: bool = False, + permissions: list[str] | None = None, + ) -> None: + self.id = user_id + self.username = username + self.is_admin = is_admin + self.permissions = ["memory"] if permissions is None else permissions + + +class _UserManager: + def __init__(self, users: dict[int, _User]) -> None: + self._users = users + + def get_by_id(self, user_id: int) -> _User | None: + return self._users.get(user_id) + + +class _AgentRow: + def __init__( + self, *, user_id: int | None, enabled: bool = True, is_shared: bool = False + ) -> None: + self.user_id = user_id + self.enabled = enabled + self.is_shared = 1 if is_shared else 0 + self.config_json = None + + +class _AgentRepo: + def __init__(self, rows: dict[str, _AgentRow]) -> None: + self._rows = rows + + def get(self, agent_id: str) -> _AgentRow | None: + return self._rows.get(agent_id) + + +class _TokenRow: + def __init__( + self, + *, + token_id: str = "tok1", + user_id: int = 1, + name: str = "codex@macbook", + expert_ids: list[str] | None = None, + token_hash: str, + revoked_at: str | None = None, + disabled_clients: list[str] | None = None, + ) -> None: + self.token_id = token_id + self.user_id = user_id + self.name = name + self.expert_ids = expert_ids + self.token_hash = token_hash + self.revoked_at = revoked_at + self.disabled_clients = disabled_clients + + +class _TokenRepo: + def __init__(self, rows: dict[str, _TokenRow] | None = None) -> None: + self.rows = rows or {} + self.touched: list[str] = [] + self.recorded: list[tuple[str, str]] = [] + + def get_by_token_hash(self, token_hash: str) -> _TokenRow | None: + return self.rows.get(token_hash) + + def touch(self, token_id: str) -> None: + self.touched.append(token_id) + + def record_client(self, token_id: str, client: str) -> None: + self.recorded.append((token_id, client)) + + def any_active(self) -> bool: + return any(row.revoked_at is None for row in self.rows.values()) + + +def _server( + *, + agents: dict[str, _AgentRow] | None = None, + users: dict[int, _User] | None = None, + token_repo: _TokenRepo | None = None, + app_runtime: Any = None, +) -> Any: + repos = SimpleNamespace( + memory_mcp_token_repo=token_repo or _TokenRepo(), + agent_repo=_AgentRepo(agents or {"A1": _AgentRow(user_id=1)}), + ) + services = SimpleNamespace(repos=repos, agent_repo=repos.agent_repo, config=None, paths=None) + return SimpleNamespace( + services=services, + user_manager=_UserManager(users or {1: _User(1, "alice")}), + app_runtime=app_runtime, + ) + + +def _tools(mcp: Any) -> dict[str, Any]: + return mcp._tool_manager._tools + + +def _run(coro: Any) -> Any: + return asyncio.run(coro) + + +def _call_tool(mcp: Any, name: str, **kwargs: Any) -> Any: + return _run(_tools(mcp)[name].fn(**kwargs)) + + +@pytest.fixture(autouse=True) +def _reset_token_touch_cache(): + mm._TOKEN_TOUCH_AT.clear() + yield + mm._TOKEN_TOUCH_AT.clear() + + +@pytest.fixture +def bind_agent(): + token = mm._current_agent_id.set("A1") + try: + yield "A1" + finally: + mm._current_agent_id.reset(token) + + +@pytest.fixture +def bind_user(): + user_cv = mm._current_user_id.set(1) + name_cv = mm._current_user_name.set("alice") + try: + yield "alice" + finally: + mm._current_user_name.reset(name_cv) + mm._current_user_id.reset(user_cv) + + +# ─── registration ─────────────────────────────────────────────────────────── + + +def test_build_registers_nine_tools(): + mcp = mm.build_memory_mcp(_server()) + assert set(_tools(mcp)) == { + "memory_search", + "memory_get", + "memory_save", + "memory_capture", + "memory_raws", + "memory_candidates", + "memory_extract", + "memory_promote", + "memory_reject", + } + + +def test_every_tool_is_async(): + """Blocking DB work must run off the event loop (review item 4).""" + mcp = mm.build_memory_mcp(_server()) + for name, tool in _tools(mcp).items(): + assert inspect.iscoroutinefunction(tool.fn), name + + +def test_tools_run_blocking_work_off_the_event_loop(bind_agent, bind_user, monkeypatch): + """Review test ask: a tool call must not block other requests.""" + import threading + + seen: list[int] = [] + + def fake_pipeline(memory, query, max_results, *, atom_only, caller=""): + seen.append(threading.get_ident()) + return [] + + monkeypatch.setattr(mm, "_pipeline_hits", fake_pipeline) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: SimpleNamespace()) + mcp = mm.build_memory_mcp(_server()) + + result = _call_tool(mcp, "memory_search", query="x") + + assert result["hits"] == [] + assert seen and seen[0] != threading.get_ident() + + +# ─── token auth middleware ────────────────────────────────────────────────── + + +def _http_scope(headers: dict[str, str]) -> dict[str, Any]: + return { + "type": "http", + "method": "POST", + "path": "/mcp/memory/", + "headers": [(k.lower().encode(), v.encode()) for k, v in headers.items()], + } + + +async def _capture_response( + middleware: Any, scope: dict[str, Any] +) -> tuple[int, list[dict[str, Any]]]: + status: list[int] = [] + bodies: list[dict[str, Any]] = [] + + async def receive() -> dict[str, Any]: + return {"type": "http.request", "body": b"", "more_body": False} + + async def send(message: dict[str, Any]) -> None: + if message["type"] == "http.response.start": + status.append(int(message["status"])) + elif message["type"] == "http.response.body": + bodies.append(message) + + await middleware(scope, receive, send) + return (status[0] if status else 0), bodies + + +async def test_middleware_rechecks_memory_permission_per_request(): + """Revoking ``memory`` must invalidate tokens that were already issued.""" + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow(token_hash=mm.hash_token(token)) + called = False + + async def inner(scope, receive, send): + nonlocal called + called = True + + server = _server(token_repo=repo, users={1: _User(1, "alice", permissions=[])}) + mw = mm._TokenAuthMiddleware(inner, server) + status, bodies = await _capture_response( + mw, _http_scope({"authorization": f"Bearer {token}"}) + ) + assert status == 403 + assert called is False + assert json.loads(bodies[0]["body"])["permission"] == "memory" + + +async def test_middleware_admin_still_bypasses_memory_permission(): + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow(token_hash=mm.hash_token(token)) + called = False + + async def inner(scope, receive, send): + nonlocal called + called = True + + server = _server( + token_repo=repo, users={1: _User(1, "alice", is_admin=True, permissions=[])} + ) + mw = mm._TokenAuthMiddleware(inner, server) + status, _ = await _capture_response( + mw, _http_scope({"authorization": f"Bearer {token}"}) + ) + assert status not in (401, 403) + assert called is True + + +async def test_middleware_rejects_missing_token(): + inner_called = False + + async def inner(scope, receive, send): + nonlocal inner_called + inner_called = True + + mw = mm._TokenAuthMiddleware(inner, _server()) + status, _ = await _capture_response(mw, _http_scope({})) + assert status == 401 + assert inner_called is False + + +async def test_middleware_rejects_unknown_and_revoked_tokens(): + repo = _TokenRepo() + mw = mm._TokenAuthMiddleware(lambda *a: None, _server(token_repo=repo)) + status, _ = await _capture_response(mw, _http_scope({"authorization": "Bearer omcp_unknown"})) + assert status == 401 + + token = "omcp_live" + repo.rows[mm.hash_token(token)] = _TokenRow( + token_hash=mm.hash_token(token), revoked_at="2026-01-01T00:00:00Z" + ) + status, _ = await _capture_response(mw, _http_scope({"authorization": f"Bearer {token}"})) + assert status == 401 + + +async def test_middleware_sets_user_from_token_and_ignores_user_header(): + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow(token_hash=mm.hash_token(token)) + seen: dict[str, Any] = {} + + async def inner(scope, receive, send): + seen["user_id"] = mm._current_user_id.get() + seen["user_name"] = mm._current_user_name.get() + seen["token_name"] = mm._current_token_name.get() + + mw = mm._TokenAuthMiddleware(inner, _server(token_repo=repo)) + status, _ = await _capture_response( + mw, + _http_scope( + { + "authorization": f"Bearer {token}", + # a client cannot name somebody else: + "x-octop-user-id": "bob", + } + ), + ) + assert status != 401 + assert seen == {"user_id": 1, "user_name": "alice", "token_name": "codex@macbook"} + assert repo.touched == ["tok1"] + + +async def test_middleware_records_identifying_client(): + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow(token_hash=mm.hash_token(token)) + called = False + + async def inner(scope, receive, send): + nonlocal called + called = True + + mw = mm._TokenAuthMiddleware(inner, _server(token_repo=repo)) + status, _ = await _capture_response( + mw, + _http_scope({"authorization": f"Bearer {token}", "x-octop-client": " codex "}), + ) + assert status != 401 and status != 403 + assert called is True + assert repo.recorded == [("tok1", "codex")] # stripped before recording + + +async def test_middleware_truncates_long_client_names(): + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow(token_hash=mm.hash_token(token)) + + async def inner(scope, receive, send): + return None + + mw = mm._TokenAuthMiddleware(inner, _server(token_repo=repo)) + await _capture_response( + mw, _http_scope({"authorization": f"Bearer {token}", "x-octop-client": "c" * 100}) + ) + assert repo.recorded == [("tok1", "c" * 64)] + + +async def test_middleware_blocks_disabled_client_after_recording_it(): + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow( + token_hash=mm.hash_token(token), disabled_clients=["codex"] + ) + called = False + + async def inner(scope, receive, send): + nonlocal called + called = True + + mw = mm._TokenAuthMiddleware(inner, _server(token_repo=repo)) + status, bodies = await _capture_response( + mw, + _http_scope({"authorization": f"Bearer {token}", "x-octop-client": "codex"}), + ) + assert status == 403 + assert called is False + assert json.loads(bodies[0]["body"]) == { + "error": "this client is disabled for this token", + "client": "codex", + } + assert repo.recorded == [("tok1", "codex")] # counted before the refusal + assert repo.touched == [] + + +async def test_middleware_allows_other_clients_and_requests_without_the_header(): + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow( + token_hash=mm.hash_token(token), disabled_clients=["codex"] + ) + seen_clients: list[tuple[int, str]] = [] + + async def inner(scope, receive, send): + seen_clients.append((int(mm._current_user_id.get() or 0), mm._current_token_name.get())) + + mw = mm._TokenAuthMiddleware(inner, _server(token_repo=repo)) + allowed, _ = await _capture_response( + mw, + _http_scope({"authorization": f"Bearer {token}", "x-octop-client": "cursor"}), + ) + assert allowed != 403 + # no header at all: unchanged behaviour — no stats, no block + allowed, _ = await _capture_response(mw, _http_scope({"authorization": f"Bearer {token}"})) + assert allowed != 403 + assert seen_clients == [(1, "codex@macbook"), (1, "codex@macbook")] + assert repo.recorded == [("tok1", "cursor")] # only the identifying request + + +async def test_middleware_survives_client_stats_failures(): + token = "omcp_live" + repo = _TokenRepo() + repo.rows[mm.hash_token(token)] = _TokenRow(token_hash=mm.hash_token(token)) + + def boom(token_id: str, client: str) -> None: + raise RuntimeError("stats store is down") + + repo.record_client = boom # type: ignore[method-assign] + called = False + + async def inner(scope, receive, send): + nonlocal called + called = True + + mw = mm._TokenAuthMiddleware(inner, _server(token_repo=repo)) + status, _ = await _capture_response( + mw, + _http_scope({"authorization": f"Bearer {token}", "x-octop-client": "codex"}), + ) + assert status != 403 + assert called is True + + +# ─── expert binding + access checks ──────────────────────────────────────── + + +async def _run_agent_router(server: Any, agent_id: str) -> tuple[int, bool]: + called = False + + async def inner(scope, receive, send): + nonlocal called + called = True + + router = mm._AgentRouter(inner, server) + status, _ = await _capture_response( + router, + _http_scope({"x-octop-agent-id": agent_id}), + ) + return status, called + + +async def test_agent_router_rejects_unknown_and_disabled_agents(): + server = _server(agents={"A1": _AgentRow(user_id=1, enabled=False)}) + user_cv = mm._current_user_id.set(1) + try: + status, called = await _run_agent_router(server, "missing") + assert status == 404 and called is False + status, called = await _run_agent_router(server, "A1") + assert status == 404 and called is False + finally: + mm._current_user_id.reset(user_cv) + + +async def test_agent_router_enforces_token_scope(): + server = _server(agents={"A1": _AgentRow(user_id=1), "A2": _AgentRow(user_id=1)}) + user_cv = mm._current_user_id.set(1) + scope_cv = mm._current_token_scope.set(["A2"]) + try: + status, called = await _run_agent_router(server, "A1") + assert status == 403 and called is False + status, called = await _run_agent_router(server, "A2") + assert called is True + finally: + mm._current_token_scope.reset(scope_cv) + mm._current_user_id.reset(user_cv) + + +async def test_agent_router_rejects_other_users_expert(): + server = _server(agents={"A1": _AgentRow(user_id=2)}) + user_cv = mm._current_user_id.set(1) + try: + status, called = await _run_agent_router(server, "A1") + assert status == 403 and called is False + finally: + mm._current_user_id.reset(user_cv) + + +async def test_agent_router_allows_shared_expert(monkeypatch): + server = _server(agents={"A1": _AgentRow(user_id=2, is_shared=True)}) + monkeypatch.setattr( + "octop.infra.users.groups.expert_visible_to", lambda *a, **k: True, raising=False + ) + user_cv = mm._current_user_id.set(1) + try: + status, called = await _run_agent_router(server, "A1") + assert called is True + finally: + mm._current_user_id.reset(user_cv) + + +_NO_AGENT_HEADER_HINT = "either bind the token to a single expert, or send X-Octop-Agent-Id" + + +async def _run_agent_router_without_header(server: Any) -> tuple[int, dict[str, Any], bool]: + """Run the router with no ``X-Octop-Agent-Id``: (status, error body, called).""" + called = False + + async def inner(scope, receive, send): + nonlocal called + called = True + + router = mm._AgentRouter(inner, server) + status, bodies = await _capture_response(router, _http_scope({})) + body = json.loads(b"".join(part.get("body", b"") for part in bodies) or b"{}") + return status, body, called + + +async def test_single_expert_token_routes_capture_without_agent_header(monkeypatch): + """唯一令牌:token 绑定一个专家时,客户端不带 X-Octop-Agent-Id 也能 capture。""" + server = _server(agents={"A1": _AgentRow(user_id=1)}) + runtime = _FakeRuntime() + scheduled: list[tuple[str, str]] = [] + monkeypatch.setattr(mm, "_memory_runtime", lambda server, agent_id: runtime) + monkeypatch.setattr( + mm, + "_schedule_extract", + lambda server, agent_id, session_id, *, promote: ( + scheduled.append((agent_id, session_id)) or False + ), + ) + mcp = mm.build_memory_mcp(server) + seen: dict[str, Any] = {} + + async def inner(scope, receive, send): + seen["agent_id"] = mm._current_agent_id.get() + await _tools(mcp)["memory_capture"].fn(content="唯一令牌", source="codex", session_id="s1") + + user_cv = mm._current_user_id.set(1) + scope_cv = mm._current_token_scope.set(["A1"]) + try: + status, bodies = await _capture_response(mm._AgentRouter(inner, server), _http_scope({})) + finally: + mm._current_token_scope.reset(scope_cv) + mm._current_user_id.reset(user_cv) + + assert status == 0 and bodies == [] + assert seen["agent_id"] == "A1" + assert len(runtime.calls) == 1 + assert scheduled == [("A1", "s1")] + + +async def test_multi_expert_token_without_agent_header_is_a_400(): + server = _server(agents={"A1": _AgentRow(user_id=1), "A2": _AgentRow(user_id=1)}) + user_cv = mm._current_user_id.set(1) + scope_cv = mm._current_token_scope.set(["A1", "A2"]) + try: + status, body, called = await _run_agent_router_without_header(server) + finally: + mm._current_token_scope.reset(scope_cv) + mm._current_user_id.reset(user_cv) + + assert status == 400 and called is False + assert body["error"] == _NO_AGENT_HEADER_HINT + assert body["allowed_expert_ids"] == ["A1", "A2"] + + +async def test_unrestricted_token_without_agent_header_is_a_400(): + server = _server(agents={"A1": _AgentRow(user_id=1)}) + user_cv = mm._current_user_id.set(1) + scope_cv = mm._current_token_scope.set(None) + try: + status, body, called = await _run_agent_router_without_header(server) + finally: + mm._current_token_scope.reset(scope_cv) + mm._current_user_id.reset(user_cv) + + assert status == 400 and called is False + assert body["error"] == _NO_AGENT_HEADER_HINT + assert "allowed_expert_ids" not in body + + +async def test_single_expert_token_still_checks_expert_access(): + """回退到唯一专家时,存在性 / 启用 / owner 可见性仍按原规则校验。""" + disabled = _server(agents={"A1": _AgentRow(user_id=1, enabled=False)}) + foreign = _server(agents={"A1": _AgentRow(user_id=2)}) + user_cv = mm._current_user_id.set(1) + scope_cv = mm._current_token_scope.set(["A1"]) + try: + status, _, called = await _run_agent_router_without_header(disabled) + assert status == 404 and called is False + status, _, called = await _run_agent_router_without_header(foreign) + assert status == 403 and called is False + finally: + mm._current_token_scope.reset(scope_cv) + mm._current_user_id.reset(user_cv) + + +# ─── capture: runtime application layer + redaction ──────────────────────── + + +class _FakeRuntime: + def __init__(self, result: dict[str, Any] | None = None) -> None: + self.calls: list[dict[str, Any]] = [] + self._result = result or {"accepted": 1} + + def capture(self, params: dict[str, Any]) -> dict[str, Any]: + self.calls.append(params) + return self._result + + +def test_capture_goes_through_runtime_with_metadata(bind_agent, bind_user, monkeypatch): + runtime = _FakeRuntime() + monkeypatch.setattr(mm, "_memory_runtime", lambda server, agent_id: runtime) + scheduled: list[tuple[str, str, bool]] = [] + monkeypatch.setattr( + mm, + "_schedule_extract", + lambda server, agent_id, session_id, *, promote: ( + scheduled.append((agent_id, session_id, promote)) or True + ), + ) + mcp = mm.build_memory_mcp(_server()) + + result = _call_tool( + mcp, + "memory_capture", + content="把 MCP 写入路径补齐", + assistant="决定改走 runtime.capture", + source="claude-code", + session_id="s1", + ) + + assert result["recorded"] is True + params = runtime.calls[0] + assert params["host"] == "claude-code" + assert params["session_id"] == "s1" + assert params["user"] == "alice" + events = params["events"] + assert [e["event_type"] for e in events] == ["user_message", "assistant_message"] + # caller goes into metadata, never into the body (review item 9): + assert "alice" not in events[0]["content"] + assert events[0]["payload"] == { + "source": "claude-code", + "source_host": "claude-code", + "caller": "alice", + } + assert scheduled == [("A1", "s1", False)] + + +def test_capture_dry_run_writes_nothing(bind_agent, bind_user, monkeypatch): + runtime = _FakeRuntime() + monkeypatch.setattr(mm, "_memory_runtime", lambda server, agent_id: runtime) + mcp = mm.build_memory_mcp(_server()) + result = _call_tool(mcp, "memory_capture", content="x", source="codex", dry_run=True) + assert result["dry_run"] is True + assert result["recorded"] is False + assert runtime.calls == [] + + +def test_capture_redacts_secrets_end_to_end(bind_agent, bind_user, monkeypatch, tmp_path): + """Review test ask: secrets in captured content must be filtered.""" + from octop_memory.application.runtime import MemoryRuntime + from octop_memory.core import Memory + + memory = Memory( + namespace="mcp-test", + backend="sqlite", + backend_config={"db_path": str(tmp_path / "memory.sqlite")}, + ) + runtime = MemoryRuntime(memory) + monkeypatch.setattr(mm, "_memory_runtime", lambda server, agent_id: runtime) + monkeypatch.setattr(mm, "_schedule_extract", lambda *a, **k: False) + mcp = mm.build_memory_mcp(_server()) + + secret = "sk-abcdefgh12345678" + _call_tool(mcp, "memory_capture", content=f"用这个 key:{secret}", source="codex") + + events = list(memory.list_raw(limit=10)) + assert events, "capture should have written an L0 event" + assert all(secret not in event.content for event in events) + assert "[REDACTED]" in events[0].content + + +def test_capture_accepts_client_parsed_events(bind_agent, bind_user, monkeypatch, tmp_path): + """Clients may parse transcripts themselves and upload typed events.""" + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + monkeypatch.setattr(mm, "_schedule_extract", lambda *a, **k: False) + mcp = mm.build_memory_mcp(_server()) + + result = _call_tool( + mcp, + "memory_capture", + events=[ + { + "event_type": "user_message", + "content": "客户端自己解析好的一轮用户发言,直接上传事件", + }, + { + "event_type": "assistant_message", + "content": "客户端解析的助手回复,也按事件形式上传", + }, + ], + source="claude-code", + extract=False, + ) + + assert result["accepted"] >= 1 + events = list(memory.list_raw(limit=5)) + assert {event.event_type for event in events} >= {"user_message"} + + +def test_capture_events_honours_dry_run(bind_agent, bind_user, monkeypatch, tmp_path): + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + mcp = mm.build_memory_mcp(_server()) + result = _call_tool( + mcp, + "memory_capture", + events=[{"event_type": "user_message", "content": "只解析不写入的客户端事件"}], + source="claude-code", + dry_run=True, + ) + assert result["recorded"] is False + assert len(result["events"]) == 1 + assert not list(memory.list_raw(limit=5)) + + +def test_capture_rejects_events_over_batch_limit(bind_agent, bind_user, monkeypatch, tmp_path): + """Review ask: never silently truncate; reject the batch instead.""" + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + mcp = mm.build_memory_mcp(_server()) + events = [{"event_type": "user_message", "content": f"事件 {i}"} for i in range(201)] + + with pytest.raises(ValueError, match="batch_too_large"): + _call_tool( + mcp, + "memory_capture", + events=events, + source="claude-code", + extract=False, + ) + assert not list(memory.list_raw(limit=5)) + + +def test_capture_events_retry_is_idempotent(bind_agent, bind_user, monkeypatch, tmp_path): + """Review ask: same batch retried must keep exactly one copy of each L0 event.""" + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + monkeypatch.setattr(mm, "_schedule_extract", lambda *a, **k: False) + mcp = mm.build_memory_mcp(_server()) + events = [ + { + "event_type": "user_message", + "content": "幂等测试的用户发言", + "payload": {"src_key": "f1:10"}, + }, + { + "event_type": "assistant_message", + "content": "幂等测试的助手回复", + "payload": {"src_key": "f1:20"}, + }, + ] + + first = _call_tool( + mcp, + "memory_capture", + events=events, + source="claude-code", + session_id="idem-1", + extract=False, + ) + second = _call_tool( + mcp, + "memory_capture", + events=events, + source="claude-code", + session_id="idem-1", + extract=False, + ) + + assert first["accepted"] == 2 + assert second["accepted"] == 0 + assert second["skipped_duplicates"] == 2 + assert len(list(memory.list_raw(session_id="idem-1", limit=50))) == 2 + + +def test_capture_events_idempotency_is_scoped_by_session( + bind_agent, bind_user, monkeypatch, tmp_path +): + """Same src_key in another session is a different event, not a duplicate.""" + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + monkeypatch.setattr(mm, "_schedule_extract", lambda *a, **k: False) + mcp = mm.build_memory_mcp(_server()) + events = [ + {"event_type": "user_message", "content": "同一个 key", "payload": {"src_key": "f1:1"}} + ] + + for session in ("scope-a", "scope-b"): + result = _call_tool( + mcp, + "memory_capture", + events=events, + source="claude-code", + session_id=session, + extract=False, + ) + assert result["accepted"] == 1 + + assert len(list(memory.list_raw(limit=10))) == 2 + + +def test_capture_events_without_src_key_dedupes_by_content_hash( + bind_agent, bind_user, monkeypatch, tmp_path +): + """Older clients without src_key still get retry idempotency.""" + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + monkeypatch.setattr(mm, "_schedule_extract", lambda *a, **k: False) + mcp = mm.build_memory_mcp(_server()) + events = [{"event_type": "user_message", "content": "没有 src_key 的事件"}] + + first = _call_tool( + mcp, "memory_capture", events=events, source="codex", session_id="hash-1", extract=False + ) + second = _call_tool( + mcp, "memory_capture", events=events, source="codex", session_id="hash-1", extract=False + ) + + assert first["accepted"] == 1 + assert second["accepted"] == 0 + assert len(list(memory.list_raw(session_id="hash-1", limit=10))) == 1 + + +def test_touch_token_is_throttled(monkeypatch): + """Review ask: stop writing last_used_at on every single MCP request.""" + calls: list[str] = [] + repo = SimpleNamespace(touch=lambda token_id: calls.append(token_id)) + clock = {"now": 1000.0} + monkeypatch.setattr(mm.time, "monotonic", lambda: clock["now"]) + + mm._TOKEN_TOUCH_AT.clear() + mm._touch_token(repo, "tok-1") + clock["now"] += 5 + mm._touch_token(repo, "tok-1") + assert calls == ["tok-1"] + + clock["now"] += mm._TOKEN_TOUCH_INTERVAL_S + mm._touch_token(repo, "tok-1") + assert calls == ["tok-1", "tok-1"] + + mm._touch_token(repo, "tok-2") + assert calls == ["tok-1", "tok-1", "tok-2"] + + +def test_shared_expert_visibility_matches_http_helper(): + """The MCP check and the HTTP routers must use one implementation.""" + from octop.infra.users.access import user_may_access_agent + + shared = SimpleNamespace(user_id=1, is_shared=1) + other = SimpleNamespace(id=2, is_admin=False, permissions=[]) + owner = SimpleNamespace(id=1, is_admin=False, permissions=[]) + admin = SimpleNamespace(id=9, is_admin=True, permissions=[]) + private = SimpleNamespace(user_id=1, is_shared=0) + + assert user_may_access_agent(shared, owner) is True + assert user_may_access_agent(shared, admin) is True + assert user_may_access_agent(private, other) is False + assert user_may_access_agent(shared, other) is True # no repos → historical HTTP behaviour + + +def test_expert_extract_promote_ignores_library_defaults(bind_agent, monkeypatch): + """octop-memory 1.0.4 defaults promote=True; external capture must stay review-only.""" + from octop_memory.application.runtime import MemoryRuntime + from octop_memory.core import Memory + + memory = Memory(namespace="promote-test", backend="sqlite", backend_config={}) + default_runtime = MemoryRuntime(memory) + assert default_runtime._extraction_cfg()["promote"] is True + + service = SimpleNamespace(_runtime=default_runtime) + monkeypatch.setattr(mm, "_live_memory_service", lambda registry, agent_id: service) + server = SimpleNamespace(app_runtime=SimpleNamespace(agent_registry=object())) + assert mm._expert_extract_promote(server, "A1") is False + + explicit = SimpleNamespace( + _runtime=MemoryRuntime(memory, config={"extraction": {"promote": True}}) + ) + monkeypatch.setattr(mm, "_live_memory_service", lambda registry, agent_id: explicit) + assert mm._expert_extract_promote(server, "A1") is True + + +def test_capture_events_cannot_spoof_identity_fields(bind_agent, bind_user, monkeypatch, tmp_path): + """Client payload may extend metadata but must not override caller/source_host.""" + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + monkeypatch.setattr(mm, "_schedule_extract", lambda *a, **k: False) + mcp = mm.build_memory_mcp(_server()) + + token_cv = mm._current_token_name.set("codex@macbook") + try: + _call_tool( + mcp, + "memory_capture", + events=[ + { + "event_type": "user_message", + "content": "伪造来源字段", + "payload": {"caller": "mallory", "source_host": "spoofed", "src_key": "x:1"}, + } + ], + source="codex", + session_id="spoof-1", + extract=False, + ) + finally: + mm._current_token_name.reset(token_cv) + + event = list(memory.list_raw(session_id="spoof-1", limit=5))[0] + assert event.payload["caller"] == "alice" + assert event.payload["source_host"] == "codex@macbook" + assert event.payload["src_key"] == "x:1" + + +# ─── capture: provenance ───────────────────────────────────────────────── + + +def test_capture_uses_the_token_name_as_source_host(bind_agent, bind_user, monkeypatch, tmp_path): + memory = _real_memory(tmp_path) + monkeypatch.setattr(mm, "_open_memory", lambda server, agent_id: memory) + monkeypatch.setattr(mm, "_schedule_extract", lambda *a, **k: False) + mcp = mm.build_memory_mcp(_server()) + + token_cv = mm._current_token_name.set("codex@macbook") + try: + _call_tool( + mcp, + "memory_capture", + content="来源标记应该用 token 名字而不是客户端自报的 source", + source="spoofed-client", + extract=False, + ) + finally: + mm._current_token_name.reset(token_cv) + + events = list(memory.list_raw(limit=5)) + assert events + assert events[-1].payload["source_host"] == "codex@macbook" + assert events[-1].payload["source"] == "spoofed-client" + + +# ─── capture: terminal transcript uploads ───────────────────────────────── + + +def _real_memory(tmp_path): + from octop_memory.core import Memory + + return Memory( + namespace="mcp-transcript-test", + backend="sqlite", + backend_config={"db_path": str(tmp_path / "memory.sqlite")}, + ) + + +# ─── save: MemoryService application layer ──────────────────────────────── + + +class _FakeService: + def __init__(self) -> None: + self.saved: list[dict[str, Any]] = [] + self.memory = SimpleNamespace(deprecate_atom=lambda *a, **k: True) + self._runtime = SimpleNamespace(_extraction_cfg=lambda: {"promote": True}) + + def save(self, content: str, *, topic=None, metadata=None): + self.saved.append({"content": content, "topic": topic, "metadata": metadata}) + return SimpleNamespace(id="n1", content=content) + + +def test_save_goes_through_memory_service(bind_agent, bind_user, monkeypatch): + service = _FakeService() + monkeypatch.setattr(mm, "_require_live_service", lambda server, agent_id: service) + mcp = mm.build_memory_mcp(_server()) + + result = _call_tool(mcp, "memory_save", content="项目约定:先跑 make all", source="codex") + + assert result["node_id"] == "n1" + saved = service.saved[0] + assert saved["content"] == "项目约定:先跑 make all" # no `说:` prefix + assert saved["metadata"] == { + "source": "codex", + "source_host": "codex", + "caller": "alice", + } + + +def test_save_supersedes_keeps_old_fact_when_new_save_fails(bind_agent, bind_user, monkeypatch): + """A failed replacement must leave the previous fact active.""" + deprecated: list[str] = [] + + class _Service: + memory = SimpleNamespace( + deprecate_atom=lambda atom_id, actor=None, note=None: deprecated.append(atom_id) or True + ) + + def save(self, content: str, *, topic=None, metadata=None): + raise RuntimeError("storage failed") + + monkeypatch.setattr(mm, "_require_live_service", lambda server, agent_id: _Service()) + mcp = mm.build_memory_mcp(_server()) + + with pytest.raises(RuntimeError, match="storage failed"): + _call_tool( + mcp, + "memory_save", + content="新事实", + source="codex", + supersedes="old-atom", + ) + assert deprecated == [] + + +def test_save_supersedes_deprecates_after_successful_save(bind_agent, bind_user, monkeypatch): + deprecated: list[tuple[str, str]] = [] + + class _Service: + memory = SimpleNamespace( + deprecate_atom=lambda atom_id, actor=None, note=None: deprecated.append((atom_id, note)) + or True + ) + + def save(self, content: str, *, topic=None, metadata=None): + assert deprecated == [] # old fact retires only after the new one is stored + return SimpleNamespace(id="n2", content=content) + + monkeypatch.setattr(mm, "_require_live_service", lambda server, agent_id: _Service()) + mcp = mm.build_memory_mcp(_server()) + + result = _call_tool( + mcp, "memory_save", content="新事实", source="codex", supersedes="old-atom" + ) + assert result["deprecated"] is True + assert deprecated == [("old-atom", "superseded by memory_save")] + + +def test_save_refuses_to_start_a_stopped_expert(bind_agent): + mcp = mm.build_memory_mcp(_server(app_runtime=None)) + with pytest.raises(RuntimeError, match="not running"): + _call_tool(mcp, "memory_save", content="x", source="codex") + + +# ─── review tools are expert-owner only ─────────────────────────────────── + + +@pytest.mark.parametrize("tool", ["memory_raws", "memory_candidates", "memory_promote"]) +def test_ops_tools_are_owner_only(bind_agent, tool): + server = _server(agents={"A1": _AgentRow(user_id=2)}) + mcp = mm.build_memory_mcp(server) + user_cv = mm._current_user_id.set(1) + try: + with pytest.raises(PermissionError): + if tool == "memory_promote": + _call_tool(mcp, tool, candidate_ids=["c1"]) + else: + _call_tool(mcp, tool) + finally: + mm._current_user_id.reset(user_cv) + + +def test_ops_tools_allow_the_owner(bind_agent, bind_user, monkeypatch): + reached = [] + + def fake_open(server, agent_id): + reached.append(agent_id) + return SimpleNamespace(search_raw=lambda *a, **k: []) + + monkeypatch.setattr(mm, "_open_memory", fake_open) + mcp = mm.build_memory_mcp(_server()) + _call_tool(mcp, "memory_raws", query="x") + assert reached == ["A1"] + + +# ─── extract: no auto-start, promote follows the expert config ──────────── + + +def _extract_service(calls: list[dict[str, Any]]) -> Any: + class _Service(_FakeService): + def extract(self, session_id, *, incremental, promote, regen_pages): + calls.append( + { + "session_id": session_id, + "incremental": incremental, + "promote": promote, + "regen_pages": regen_pages, + } + ) + return {"candidates": 2, "promotion": {"promoted": 1}} + + return _Service() + + +def test_extract_follows_expert_promote_config(bind_agent, bind_user, monkeypatch): + calls: list[dict[str, Any]] = [] + monkeypatch.setattr( + mm, "_require_live_service", lambda server, agent_id: _extract_service(calls) + ) + monkeypatch.setattr(mm, "_expert_extract_promote", lambda server, agent_id: True) + mcp = mm.build_memory_mcp(_server()) + result = _call_tool(mcp, "memory_extract", session_id="s1") + assert result["promoted"] == 1 + assert calls[0]["promote"] is True + assert calls[0]["incremental"] is True + + +def test_extract_explicit_promote_false_wins(bind_agent, bind_user, monkeypatch): + calls: list[dict[str, Any]] = [] + monkeypatch.setattr( + mm, "_require_live_service", lambda server, agent_id: _extract_service(calls) + ) + mcp = mm.build_memory_mcp(_server()) + _call_tool(mcp, "memory_extract", session_id="s1", promote=False) + assert calls[0]["promote"] is False + + +def test_expert_promote_reads_only_explicit_config(): + explicit = SimpleNamespace( + _config=SimpleNamespace(extraction={"promote": True}), + _extraction_cfg=lambda: {"promote": True}, + ) + service = SimpleNamespace(_runtime=explicit) + agent = SimpleNamespace(_memory_runtime=SimpleNamespace(service=service)) + registry = SimpleNamespace(get_agent=lambda agent_id: agent) + server = _server(app_runtime=SimpleNamespace(agent_registry=registry)) + assert mm._expert_extract_promote(server, "A1") is True + + # Library default (merged in _extraction_cfg) must not enable promotion. + defaulted = SimpleNamespace( + _config=SimpleNamespace(extraction={}), + _extraction_cfg=lambda: {"promote": True}, + ) + monkeypatch_service = SimpleNamespace(_runtime=defaulted) + registry = SimpleNamespace( + get_agent=lambda agent_id: SimpleNamespace( + _memory_runtime=SimpleNamespace(service=monkeypatch_service) + ) + ) + server = _server(app_runtime=SimpleNamespace(agent_registry=registry)) + assert mm._expert_extract_promote(server, "A1") is False + + # no live service -> review queue default + assert mm._expert_extract_promote(_server(app_runtime=None), "A1") is False + + +async def test_schedule_extract_never_starts_a_stopped_expert(monkeypatch): + server = _server(app_runtime=SimpleNamespace(agent_registry=object())) + assert mm._schedule_extract(server, "A1", "s1", promote=False) is False + + +# ─── mount + lifespan ───────────────────────────────────────────────────── + + +def test_mount_is_fail_closed(monkeypatch): + monkeypatch.delenv("OCTOP_MEMORY_MCP_ENABLED", raising=False) + assert mm._memory_mcp_enabled() is False + monkeypatch.setenv("OCTOP_MEMORY_MCP_ENABLED", "1") + assert mm._memory_mcp_enabled() is True + + +def test_lifespan_chain_keeps_the_previous_hooks(): + from contextlib import asynccontextmanager + + seen: list[str] = [] + + @asynccontextmanager + async def previous(app): + seen.append("previous-enter") + yield + seen.append("previous-exit") + + chained = mm._chain_lifespan(previous, []) + + async def _run_lifespan() -> None: + async with chained(None): + seen.append("body") + + asyncio.run(_run_lifespan()) + assert seen == ["previous-enter", "body", "previous-exit"] diff --git a/tests/unit/api/test_memory_mcp_token_api.py b/tests/unit/api/test_memory_mcp_token_api.py new file mode 100644 index 0000000000..8f573fc091 --- /dev/null +++ b/tests/unit/api/test_memory_mcp_token_api.py @@ -0,0 +1,371 @@ +"""Unit tests for the memory MCP token HTTP adapter.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from types import SimpleNamespace +from typing import Any + +import pytest +from fastapi import FastAPI +from fastapi.responses import JSONResponse +from fastapi.testclient import TestClient +from starlette.requests import Request + +from octop.api.deps import current_user, get_server +from octop.api.routers import memory_mcp +from octop.infra.agents.memory_tokens import TOKEN_PREFIX, hash_token +from octop.infra.db.migrate import run_migrations +from octop.infra.db.pool import SqlitePool +from octop.infra.db.repos.users import UserRepo +from octop.infra.db.services import RepoBundle +from octop.infra.errors import OctopError +from octop.infra.users.identity import Role, User +from octop.infra.utils.ulid import new_ulid + + +@dataclass +class Seeded: + db: SqlitePool + repos: RepoBundle + owner: User + other: User + owner_agent: str + other_agent: str + + +def _seed(tmp_path: Path) -> Seeded: + db = SqlitePool(tmp_path / "octop.db") + run_migrations(db) + repos = RepoBundle.from_pool(db) + users = UserRepo(db) + owner_id = users.create( + username="owner", password_hash="h", role="user", permissions=["memory"] + ) + other_id = users.create( + username="other", password_hash="h", role="user", permissions=["memory"] + ) + owner_agent = new_ulid() + other_agent = new_ulid() + repos.agent_repo.create(agent_id=owner_agent, user_id=owner_id, name="owner-bot") + repos.agent_repo.create(agent_id=other_agent, user_id=other_id, name="other-bot") + return Seeded( + db=db, + repos=repos, + owner=User( + id=owner_id, + username="owner", + role=Role.USER, + display_name=None, + permissions=["memory"], + ), + other=User( + id=other_id, + username="other", + role=Role.USER, + display_name=None, + permissions=["memory"], + ), + owner_agent=owner_agent, + other_agent=other_agent, + ) + + +@pytest.fixture +def seeded(tmp_path: Path) -> Seeded: + return _seed(tmp_path) + + +def _client(seeded: Seeded, user: User) -> TestClient: + server = SimpleNamespace(services=SimpleNamespace(repos=seeded.repos)) + app = FastAPI() + app.include_router(memory_mcp.router) + + @app.exception_handler(OctopError) + async def _octop_error(request: Request, exc: OctopError) -> JSONResponse: + return JSONResponse(status_code=exc.status, content=exc.to_envelope()) + + app.dependency_overrides[get_server] = lambda: server + app.dependency_overrides[current_user] = lambda: user + return TestClient(app) + + +def _create_token(client: TestClient, **body: Any) -> dict[str, Any]: + response = client.post("/memory-mcp/tokens", json={"name": "codex@macbook", **body}) + assert response.status_code == 201, response.text + return response.json() + + +def test_create_returns_plaintext_once(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + data = _create_token(client, expert_ids=[seeded.owner_agent]) + + token = data["token"] + assert token.startswith(TOKEN_PREFIX) + assert data["token_hint"] == f"{token[:9]}…{token[-4:]}" + assert data["name"] == "codex@macbook" + assert data["expert_ids"] == [seeded.owner_agent] + assert data["revoked_at"] is None + assert data["last_used_at"] is None + + row = seeded.repos.memory_mcp_token_repo.get_for_user(data["token_id"], user_id=seeded.owner.id) + assert row is not None + assert row.token_hash == hash_token(token) + assert row.token_hint == data["token_hint"] + + +def test_list_never_returns_plaintext(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + token = _create_token(client)["token"] + + response = client.get("/memory-mcp/tokens") + assert response.status_code == 200 + items = response.json() + assert len(items) == 1 + assert "token" not in items[0] + assert token not in response.text + + +def test_revoke_only_own_token(seeded: Seeded) -> None: + owner_client = _client(seeded, seeded.owner) + token_id = _create_token(owner_client)["token_id"] + + other_client = _client(seeded, seeded.other) + foreign = other_client.delete(f"/memory-mcp/tokens/{token_id}") + assert foreign.status_code == 404 + assert foreign.json()["error"]["code"] == "NOT_FOUND" + row = seeded.repos.memory_mcp_token_repo.get_for_user(token_id, user_id=seeded.owner.id) + assert row is not None + assert row.revoked_at is None + + first = owner_client.delete(f"/memory-mcp/tokens/{token_id}") + assert first.status_code == 200 + assert first.json() == {"revoked": True} + second = owner_client.delete(f"/memory-mcp/tokens/{token_id}") + assert second.status_code == 200 + assert second.json() == {"revoked": False} + + +def test_create_rejects_inaccessible_expert(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + + forbidden = client.post( + "/memory-mcp/tokens", + json={"name": "codex@macbook", "expert_ids": [seeded.other_agent]}, + ) + assert forbidden.status_code == 403 + assert forbidden.json()["error"]["code"] == "FORBIDDEN" + + missing = client.post( + "/memory-mcp/tokens", + json={"name": "codex@macbook", "expert_ids": [new_ulid()]}, + ) + assert missing.status_code == 404 + assert missing.json()["error"]["code"] == "AGENT_NOT_FOUND" + + assert seeded.repos.memory_mcp_token_repo.list_for_user(seeded.owner.id) == [] + + +def test_empty_expert_ids_means_unrestricted(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + data = _create_token(client, expert_ids=[]) + assert data["expert_ids"] is None + + +def test_patch_renames_and_keeps_the_experts(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + created = _create_token(client, expert_ids=[seeded.owner_agent]) + + response = client.patch( + f"/memory-mcp/tokens/{created['token_id']}", json={"name": "claude@laptop"} + ) + + assert response.status_code == 200, response.text + patched = response.json() + assert patched["name"] == "claude@laptop" + assert patched["expert_ids"] == [seeded.owner_agent] + assert patched["token_hint"] == created["token_hint"] + assert patched["revoked_at"] is None + assert "token" not in patched + assert created["token"] not in response.text + + +def test_patch_rebinds_experts_and_clears_the_restriction(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + token_id = _create_token(client, expert_ids=[seeded.owner_agent])["token_id"] + + rebound = client.patch(f"/memory-mcp/tokens/{token_id}", json={"expert_ids": []}) + assert rebound.status_code == 200, rebound.text + assert rebound.json()["expert_ids"] is None + + rebound = client.patch( + f"/memory-mcp/tokens/{token_id}", json={"expert_ids": [seeded.owner_agent]} + ) + assert rebound.json()["expert_ids"] == [seeded.owner_agent] + + cleared = client.patch(f"/memory-mcp/tokens/{token_id}", json={"expert_ids": None}) + assert cleared.status_code == 200, cleared.text + assert cleared.json()["expert_ids"] is None + + row = seeded.repos.memory_mcp_token_repo.get_for_user(token_id, user_id=seeded.owner.id) + assert row is not None + assert row.expert_ids is None + + +def test_patch_other_users_token_is_not_found(seeded: Seeded) -> None: + token_id = _create_token(_client(seeded, seeded.owner))["token_id"] + + response = _client(seeded, seeded.other).patch( + f"/memory-mcp/tokens/{token_id}", json={"name": "hijack"} + ) + + assert response.status_code == 404 + assert response.json()["error"]["code"] == "NOT_FOUND" + row = seeded.repos.memory_mcp_token_repo.get_for_user(token_id, user_id=seeded.owner.id) + assert row is not None and row.name == "codex@macbook" + + +def test_patch_revoked_token_is_a_conflict(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + token_id = _create_token(client)["token_id"] + assert client.delete(f"/memory-mcp/tokens/{token_id}").status_code == 200 + + response = client.patch(f"/memory-mcp/tokens/{token_id}", json={"name": "late"}) + + assert response.status_code == 409 + assert response.json()["error"]["code"] == "FORBIDDEN" + assert "revoked" in response.json()["error"]["message"] + + +def test_patch_rejects_inaccessible_expert_and_keeps_the_row(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + token_id = _create_token(client, expert_ids=[seeded.owner_agent])["token_id"] + + forbidden = client.patch( + f"/memory-mcp/tokens/{token_id}", json={"expert_ids": [seeded.other_agent]} + ) + assert forbidden.status_code == 403 + assert forbidden.json()["error"]["code"] == "FORBIDDEN" + + missing = client.patch(f"/memory-mcp/tokens/{token_id}", json={"expert_ids": [new_ulid()]}) + assert missing.status_code == 404 + assert missing.json()["error"]["code"] == "AGENT_NOT_FOUND" + + row = seeded.repos.memory_mcp_token_repo.get_for_user(token_id, user_id=seeded.owner.id) + assert row is not None and row.expert_ids == [seeded.owner_agent] + + +def test_patch_requires_a_field(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + token_id = _create_token(client)["token_id"] + + assert client.patch(f"/memory-mcp/tokens/{token_id}", json={}).status_code == 422 + assert client.patch(f"/memory-mcp/tokens/{token_id}", json={"name": None}).status_code == 422 + + +def test_create_requires_memory_permission(seeded: Seeded) -> None: + denied = User( + id=seeded.owner.id, + username="owner", + role=Role.USER, + display_name=None, + permissions=[], + ) + response = _client(seeded, denied).post("/memory-mcp/tokens", json={"name": "codex@macbook"}) + assert response.status_code == 403 + assert response.json()["error"]["details"]["permission"] == "memory" + + +def test_create_reports_empty_client_state(seeded: Seeded) -> None: + data = _create_token(_client(seeded, seeded.owner)) + assert data["disabled_clients"] is None + assert data["client_stats"] is None + + +def test_list_reports_client_stats_and_disabled_clients(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + created = _create_token(client) + repo = seeded.repos.memory_mcp_token_repo + repo.record_client(created["token_id"], "codex", now="2026-01-01T00:00:00Z") + repo.record_client(created["token_id"], "codex", now="2026-01-02T00:00:00Z") + + patched = client.patch( + f"/memory-mcp/tokens/{created['token_id']}", json={"disabled_clients": ["cursor"]} + ) + assert patched.status_code == 200, patched.text + assert patched.json()["disabled_clients"] == ["cursor"] + assert patched.json()["client_stats"]["codex"]["count"] == 2 + + items = client.get("/memory-mcp/tokens").json() + assert items[0]["disabled_clients"] == ["cursor"] + assert items[0]["client_stats"] == { + "codex": { + "first_seen": "2026-01-01T00:00:00Z", + "last_seen": "2026-01-02T00:00:00Z", + "count": 2, + } + } + + +def test_patch_sets_and_clears_disabled_clients(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + token_id = _create_token(client)["token_id"] + repo = seeded.repos.memory_mcp_token_repo + + # Only disabled_clients: the expert list and name stay untouched. + set_response = client.patch( + f"/memory-mcp/tokens/{token_id}", json={"disabled_clients": ["codex", "cursor"]} + ) + assert set_response.status_code == 200, set_response.text + assert set_response.json()["disabled_clients"] == ["codex", "cursor"] + assert set_response.json()["name"] == "codex@macbook" + row = repo.get_for_user(token_id, user_id=seeded.owner.id) + assert row is not None and row.disabled_clients == ["codex", "cursor"] + + cleared = client.patch(f"/memory-mcp/tokens/{token_id}", json={"disabled_clients": []}) + assert cleared.status_code == 200, cleared.text + assert cleared.json()["disabled_clients"] is None + row = repo.get_for_user(token_id, user_id=seeded.owner.id) + assert row is not None and row.disabled_clients is None + + client.patch(f"/memory-mcp/tokens/{token_id}", json={"disabled_clients": ["kiro"]}) + nulled = client.patch(f"/memory-mcp/tokens/{token_id}", json={"disabled_clients": None}) + assert nulled.status_code == 200, nulled.text + assert nulled.json()["disabled_clients"] is None + row = repo.get_for_user(token_id, user_id=seeded.owner.id) + assert row is not None and row.disabled_clients is None + + +def test_rotate_issues_a_new_secret_and_invalidates_the_old_one(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + created = _create_token(client, expert_ids=[seeded.owner_agent]) + repo = seeded.repos.memory_mcp_token_repo + + response = client.post(f"/memory-mcp/tokens/{created['token_id']}/rotate") + assert response.status_code == 200, response.text + rotated = response.json() + assert rotated["token_id"] == created["token_id"] + assert rotated["token"] != created["token"] + assert rotated["expert_ids"] == [seeded.owner_agent] + assert rotated["token_hint"] != created["token_hint"] + + row = repo.get_by_token_hash(hash_token(created["token"])) + assert row is None # the old plaintext no longer resolves + row = repo.get_by_token_hash(hash_token(rotated["token"])) + assert row is not None and row.token_id == created["token_id"] + + +def test_rotate_other_users_token_is_not_found(seeded: Seeded) -> None: + created = _create_token(_client(seeded, seeded.owner)) + other = _client(seeded, seeded.other) + response = other.post(f"/memory-mcp/tokens/{created['token_id']}/rotate") + assert response.status_code == 404 + + +def test_rotate_revoked_token_is_a_conflict(seeded: Seeded) -> None: + client = _client(seeded, seeded.owner) + token_id = _create_token(client)["token_id"] + assert client.delete(f"/memory-mcp/tokens/{token_id}").status_code == 200 + response = client.post(f"/memory-mcp/tokens/{token_id}/rotate") + assert response.status_code == 409 diff --git a/tests/unit/backup/test_system_archive.py b/tests/unit/backup/test_system_archive.py index f0612e7cb8..b74ab202a4 100644 --- a/tests/unit/backup/test_system_archive.py +++ b/tests/unit/backup/test_system_archive.py @@ -1178,7 +1178,7 @@ def test_restore_repairs_old_physical_schema_with_current_watermark(tmp_path: Pa "SELECT instance_id, shared FROM connectors WHERE instance_id = 'instance-1'" ).fetchone() - assert result["schema_version"] == 25 + assert result["schema_version"] == 26 assert "shared" in columns assert connector is not None assert connector["shared"] == 0 @@ -1232,7 +1232,7 @@ def test_refuse_newer_schema_backup_before_database_replace( assert excinfo.value.code == ErrorCode.BACKUP_SCHEMA_INCOMPATIBLE assert excinfo.value.details == { "archive_schema_version": 999, - "runtime_schema_version": 25, + "runtime_schema_version": 26, } with pool.connect() as conn: assert ( diff --git a/tests/unit/db/test_agent_profile_columns.py b/tests/unit/db/test_agent_profile_columns.py index 2f8d875de0..adae385dd9 100644 --- a/tests/unit/db/test_agent_profile_columns.py +++ b/tests/unit/db/test_agent_profile_columns.py @@ -119,7 +119,7 @@ def test_migration_007_backfills_profile_columns(tmp_path: Path) -> None: with pool.connect() as conn: version = conn.execute("SELECT version FROM _schema_version").fetchone()[0] row = conn.execute("SELECT * FROM agents WHERE agent_id = ?", ("ag1",)).fetchone() - assert version == 25 + assert version == 26 assert row["template_name"] == "general-assistant" assert row["icon_name"] == "zap" assert row["icon_url"] == "https://cdn.example.com/a.png" diff --git a/tests/unit/db/test_clip_thread_title.py b/tests/unit/db/test_clip_thread_title.py index f52a240f61..54893eae70 100644 --- a/tests/unit/db/test_clip_thread_title.py +++ b/tests/unit/db/test_clip_thread_title.py @@ -82,7 +82,7 @@ def test_migration_003_repairs_stored_hard_cuts(tmp_path: Path) -> None: with pool.connect() as conn: v = conn.execute("SELECT version FROM _schema_version").fetchone()[0] title = conn.execute("SELECT title FROM threads WHERE thread_id = ?", ("t1",)).fetchone()[0] - assert v == 25 + assert v == 26 assert title == "x" * 39 + "…" # Idempotent repair assert repair_all_legacy_thread_titles(pool) == 0 diff --git a/tests/unit/db/test_db_pool.py b/tests/unit/db/test_db_pool.py index 911a6f9734..25255e72fd 100644 --- a/tests/unit/db/test_db_pool.py +++ b/tests/unit/db/test_db_pool.py @@ -146,7 +146,7 @@ def test_run_migrations_idempotent(db: SqlitePool): sso_indexes = { r["name"] for r in conn.execute("PRAGMA index_list(sso_providers)").fetchall() } - assert v == 25 + assert v == 26 assert "login_failed_count" in cols assert "login_locked_until" in cols assert {"mfa_version", "mfa_failed_count", "mfa_locked_until", "password_version"}.issubset( @@ -282,7 +282,7 @@ def test_migration_002_idempotent_when_column_already_present(tmp_path: Path) -> with pool.connect() as conn: v = conn.execute("SELECT version FROM _schema_version").fetchone()[0] cron_cols = {r["name"] for r in conn.execute("PRAGMA table_info(cron_jobs)").fetchall()} - assert v == 25 + assert v == 26 assert "mcp_servers" in cron_cols assert "skill_packages" in { r["name"] @@ -426,7 +426,7 @@ def test_stuck_version_6_without_permissions_column_is_repaired(tmp_path: Path) with pool.connect() as conn: cols = {r["name"] for r in conn.execute("PRAGMA table_info(users)").fetchall()} version = conn.execute("SELECT version FROM _schema_version").fetchone()[0] - assert version == 25 + assert version == 26 assert "permissions" in cols @@ -451,7 +451,7 @@ def test_schema_v10_without_projection_tables_is_repaired(tmp_path: Path) -> Non } kb_cols = {r["name"] for r in conn.execute("PRAGMA table_info(knowledge_bases)").fetchall()} cron_cols = {r["name"] for r in conn.execute("PRAGMA table_info(cron_jobs)").fetchall()} - assert version == 25 + assert version == 26 assert {"thread_messages", "thread_history_projection", "trajectory_events"}.issubset( table_names ) @@ -486,7 +486,7 @@ def test_ahead_of_max_schema_version_clamps_to_max(tmp_path: Path) -> None: r["name"] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall() } - assert version == 25 + assert version == 26 assert "skill_package_id" in pkg_cols assert "published_expert_id" in pub_cols assert "user_invites" in invite_tables @@ -580,7 +580,7 @@ def test_pre_squash_schema_version_clamped_and_knowledge_tables_filled( for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall() } user_cols = {r["name"] for r in conn.execute("PRAGMA table_info(users)").fetchall()} - assert version == 25 + assert version == 26 assert "permissions" in user_cols assert { "published_experts", @@ -786,7 +786,7 @@ def test_v14_to_v15_adds_sso_provider_kind_without_rebuilding(tmp_path: Path) -> bound = conn.execute( "SELECT sso_provider_id FROM users WHERE username = 'sso-admin'" ).fetchone()[0] - assert version == 25 + assert version == 26 assert int(row["id"]) == int(provider_id) assert row["kind"] == "oidc" assert row["extra"] == "{}" diff --git a/tests/unit/db/test_memory_mcp_tokens.py b/tests/unit/db/test_memory_mcp_tokens.py new file mode 100644 index 0000000000..926f792f29 --- /dev/null +++ b/tests/unit/db/test_memory_mcp_tokens.py @@ -0,0 +1,305 @@ +"""Unit tests for memory MCP token helpers, schema v26, and the repo.""" + +from __future__ import annotations + +import json +from datetime import datetime +from pathlib import Path + +import pytest + +from octop.infra.agents.memory_tokens import ( + TOKEN_PREFIX, + generate_token, + hash_token, + token_hint, + token_matches, +) +from octop.infra.db.migrate import run_migrations +from octop.infra.db.pool import SqlitePool +from octop.infra.db.repos.memory_mcp_tokens import MemoryMcpTokenRepo +from octop.infra.db.repos.users import UserRepo +from octop.infra.utils.ulid import new_ulid + + +@pytest.fixture +def db(tmp_path: Path) -> SqlitePool: + pool = SqlitePool(tmp_path / "octop.db") + run_migrations(pool) + return pool + + +@pytest.fixture +def repo(db: SqlitePool) -> MemoryMcpTokenRepo: + return MemoryMcpTokenRepo(db) + + +def _user(db: SqlitePool, username: str = "alice") -> int: + return UserRepo(db).create(username=username, password_hash="h", role="user") + + +def _issue( + repo: MemoryMcpTokenRepo, + user_id: int, + *, + name: str = "codex@macbook", + expert_ids: list[str] | None = None, +) -> tuple[str, str]: + """Create a token; return ``(plaintext, token_id)``.""" + plaintext, digest = generate_token() + token_id = new_ulid() + repo.create( + user_id=user_id, + name=name, + expert_ids=expert_ids, + token_id=token_id, + token_hash=digest, + token_hint=token_hint(plaintext), + ) + return plaintext, token_id + + +def test_generate_token_prefix_and_digest() -> None: + plaintext, digest = generate_token() + assert plaintext.startswith(TOKEN_PREFIX) + assert len(plaintext) > len(TOKEN_PREFIX) + 32 + assert digest == hash_token(plaintext) + assert len(digest) == 64 + assert plaintext != generate_token()[0] + + +def test_token_matches_compares_digests() -> None: + plaintext, digest = generate_token() + assert token_matches(plaintext, digest) + assert not token_matches(plaintext + "x", digest) + + +def test_token_hint_masks_middle() -> None: + plaintext, _ = generate_token() + hint = token_hint(plaintext) + assert hint == f"{plaintext[:9]}…{plaintext[-4:]}" + assert "…" in hint + assert hint.startswith(TOKEN_PREFIX) + + +def test_schema_v26_creates_table(db: SqlitePool) -> None: + with db.connect() as conn: + version = conn.execute("SELECT version FROM _schema_version").fetchone()[0] + tables = { + r["name"] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'") + } + indexes = { + r["name"] for r in conn.execute("PRAGMA index_list(memory_mcp_tokens)").fetchall() + } + columns = { + r["name"] for r in conn.execute("PRAGMA table_info(memory_mcp_tokens)").fetchall() + } + assert version == 26 + assert "memory_mcp_tokens" in tables + assert "idx_memory_mcp_tokens_user" in indexes + assert { + "id", + "token_id", + "user_id", + "name", + "expert_ids", + "disabled_clients", + "client_stats", + "token_hash", + "token_hint", + "created_at", + "last_used_at", + "revoked_at", + } == columns + + +def test_create_persists_digest_only(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + user_id = _user(db) + plaintext, token_id = _issue(repo, user_id) + + row = repo.get_for_user(token_id, user_id=user_id) + assert row is not None + assert row.token_id == token_id + assert row.user_id == user_id + assert row.name == "codex@macbook" + assert row.expert_ids is None + assert row.token_hash == hash_token(plaintext) + assert row.token_hint == token_hint(plaintext) + assert row.last_used_at is None + assert row.revoked_at is None + datetime.fromisoformat(row.created_at.replace("Z", "+00:00")) + + with db.connect() as conn: + stored = conn.execute( + "SELECT * FROM memory_mcp_tokens WHERE token_id = ?", (token_id,) + ).fetchone() + assert plaintext not in json.dumps(dict(stored)) + + +def test_expert_ids_json_round_trip(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + user_id = _user(db) + _, token_id = _issue(repo, user_id, expert_ids=["expert-a", "expert-b"]) + + row = repo.get_for_user(token_id, user_id=user_id) + assert row is not None + assert row.expert_ids == ["expert-a", "expert-b"] + + with db.connect() as conn: + raw = conn.execute( + "SELECT expert_ids FROM memory_mcp_tokens WHERE token_id = ?", (token_id,) + ).fetchone()["expert_ids"] + assert json.loads(raw) == ["expert-a", "expert-b"] + + +def test_list_for_user_newest_first_and_scoped(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + alice = _user(db, "alice") + bob = _user(db, "bob") + _, first = _issue(repo, alice, name="first") + _, second = _issue(repo, alice, name="second") + _issue(repo, bob, name="bob-token") + + rows = repo.list_for_user(alice) + assert [row.token_id for row in rows] == [second, first] + assert repo.list_for_user(bob)[0].name == "bob-token" + + +def test_get_by_token_hash_returns_revoked_row(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + user_id = _user(db) + plaintext, token_id = _issue(repo, user_id) + assert repo.revoke(token_id, user_id=user_id) is True + + row = repo.get_by_token_hash(hash_token(plaintext)) + assert row is not None + assert row.token_id == token_id + assert row.revoked_at is not None + assert repo.get_by_token_hash(hash_token("omcp_unknown")) is None + + +def test_get_for_user_hides_other_users_tokens(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + alice = _user(db, "alice") + bob = _user(db, "bob") + _, token_id = _issue(repo, alice) + assert repo.get_for_user(token_id, user_id=bob) is None + + +def test_revoke_is_idempotent(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + alice = _user(db, "alice") + bob = _user(db, "bob") + _, token_id = _issue(repo, alice) + + assert repo.revoke(token_id, user_id=bob) is False + assert repo.revoke(token_id, user_id=alice) is True + assert repo.revoke(token_id, user_id=alice) is False + row = repo.get_for_user(token_id, user_id=alice) + assert row is not None + assert row.revoked_at is not None + + +def test_any_active_ignores_revoked(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + user_id = _user(db) + assert repo.any_active() is False + _, token_id = _issue(repo, user_id) + assert repo.any_active() is True + repo.revoke(token_id, user_id=user_id) + assert repo.any_active() is False + + +def test_touch_sets_last_used_at(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + user_id = _user(db) + _, token_id = _issue(repo, user_id) + repo.touch(token_id) + + row = repo.get_for_user(token_id, user_id=user_id) + assert row is not None + assert row.last_used_at is not None + datetime.fromisoformat(row.last_used_at.replace("Z", "+00:00")) + + +def test_update_disabled_clients_round_trip(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + user_id = _user(db) + _, token_id = _issue(repo, user_id) + row = repo.get_for_user(token_id, user_id=user_id) + assert row is not None + assert row.disabled_clients is None + + updated = repo.update( + token_id, + user_id=user_id, + name=row.name, + expert_ids=row.expert_ids, + disabled_clients=["codex", "cursor"], + ) + assert updated is not None + assert updated.disabled_clients == ["codex", "cursor"] + stored = repo.get_for_user(token_id, user_id=user_id) + assert stored is not None + assert stored.disabled_clients == ["codex", "cursor"] + + # An empty list is the same as "no restriction". + cleared = repo.update( + token_id, + user_id=user_id, + name=row.name, + expert_ids=row.expert_ids, + disabled_clients=[], + ) + assert cleared is not None + assert cleared.disabled_clients is None + + repo.update( + token_id, + user_id=user_id, + name=row.name, + expert_ids=row.expert_ids, + disabled_clients=["kiro"], + ) + released = repo.update( + token_id, user_id=user_id, name="renamed", expert_ids=None, disabled_clients=None + ) + assert released is not None + assert released.disabled_clients is None + + +def test_record_client_merges_counts(db: SqlitePool, repo: MemoryMcpTokenRepo) -> None: + user_id = _user(db) + _, token_id = _issue(repo, user_id) + + repo.record_client(token_id, "codex", now="2026-01-01T00:00:00Z") + repo.record_client(token_id, "codex", now="2026-01-02T00:00:00Z") + repo.record_client(token_id, "cursor", now="2026-01-03T00:00:00Z") + + row = repo.get_for_user(token_id, user_id=user_id) + assert row is not None + assert row.client_stats == { + "codex": { + "first_seen": "2026-01-01T00:00:00Z", + "last_seen": "2026-01-02T00:00:00Z", + "count": 2, + }, + "cursor": { + "first_seen": "2026-01-03T00:00:00Z", + "last_seen": "2026-01-03T00:00:00Z", + "count": 1, + }, + } + + with db.connect() as conn: + raw = conn.execute( + "SELECT client_stats FROM memory_mcp_tokens WHERE token_id = ?", (token_id,) + ).fetchone()["client_stats"] + assert json.loads(raw)["codex"]["count"] == 2 + + +def test_record_client_ignores_missing_and_revoked_tokens( + db: SqlitePool, repo: MemoryMcpTokenRepo +) -> None: + user_id = _user(db) + _, token_id = _issue(repo, user_id) + + repo.record_client("tok_missing", "codex") # no row: still a no-op + repo.revoke(token_id, user_id=user_id) + repo.record_client(token_id, "codex") + + row = repo.get_for_user(token_id, user_id=user_id) + assert row is not None + assert row.client_stats is None diff --git a/tests/unit/db/test_published_experts_repo.py b/tests/unit/db/test_published_experts_repo.py index 5bef317516..9c96c6e020 100644 --- a/tests/unit/db/test_published_experts_repo.py +++ b/tests/unit/db/test_published_experts_repo.py @@ -27,7 +27,7 @@ def test_published_experts_table_exists(db: SqlitePool) -> None: v = conn.execute("SELECT version FROM _schema_version").fetchone()[0] cols = {r["name"] for r in conn.execute("PRAGMA table_info(published_experts)").fetchall()} assert "published_experts" in names - assert v == 25 + assert v == 26 assert "published_expert_id" in cols diff --git a/tests/unit/db/test_repo_knowledge.py b/tests/unit/db/test_repo_knowledge.py index 641714afa5..194951a7a0 100644 --- a/tests/unit/db/test_repo_knowledge.py +++ b/tests/unit/db/test_repo_knowledge.py @@ -50,7 +50,7 @@ def test_knowledge_tables_migrated(db: SqlitePool) -> None: "knowledge_bases", "knowledge_documents", }.issubset(names) - assert v == 25 + assert v == 26 assert "knowledge_base_members" not in names cols = {r["name"] for r in conn.execute("PRAGMA table_info(knowledge_bases)").fetchall()} assert "knowledge_base_id" in cols diff --git a/tests/unit/db/test_skill_package_icons.py b/tests/unit/db/test_skill_package_icons.py index 812dbcf25e..a780b998c6 100644 --- a/tests/unit/db/test_skill_package_icons.py +++ b/tests/unit/db/test_skill_package_icons.py @@ -91,7 +91,7 @@ def test_migration_002_idempotent_when_icon_columns_already_present(tmp_path: Pa "SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='skill_packages'" ) } - assert v == 25 + assert v == 26 assert "icon_name" in cols assert "icon_url" in cols assert "skill_package_id" in cols @@ -110,7 +110,7 @@ def test_repair_legacy_schema_adds_icon_columns_at_version_2(tmp_path: Path) -> with pool.connect() as conn: v = conn.execute("SELECT version FROM _schema_version").fetchone()[0] cols = {r["name"] for r in conn.execute("PRAGMA table_info(skill_packages)").fetchall()} - assert v == 25 + assert v == 26 assert "icon_name" in cols assert "icon_url" in cols assert "skill_package_id" in cols diff --git a/tests/unit/db/test_skill_packages_repo.py b/tests/unit/db/test_skill_packages_repo.py index c51096bd9d..d259a323e9 100644 --- a/tests/unit/db/test_skill_packages_repo.py +++ b/tests/unit/db/test_skill_packages_repo.py @@ -28,7 +28,7 @@ def test_skill_packages_table_exists(db: SqlitePool) -> None: v = conn.execute("SELECT version FROM _schema_version").fetchone()[0] cols = {r["name"] for r in conn.execute("PRAGMA table_info(skill_packages)").fetchall()} assert "skill_packages" in names - assert v == 25 + assert v == 26 assert "skill_package_id" in cols diff --git a/tests/unit/users/test_group_access.py b/tests/unit/users/test_group_access.py index 816b6d4a59..d188824fb2 100644 --- a/tests/unit/users/test_group_access.py +++ b/tests/unit/users/test_group_access.py @@ -36,7 +36,7 @@ def test_schema_version_includes_user_groups(repos: RepoBundle) -> None: row["name"] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall() } - assert version == 25 + assert version == 26 assert {"user_group", "user_group_member", "resource_group_grant"}.issubset(names)