用途：创建或更新受信任的本地 Letta Code mod 文件。Mod 是受信任的本地代码，通过 mod API 添加小型可组合能力，而非导入应用内部实现。动态的 agent/conversation/workspace/model 状态以 ctx 传给工具、命令、事件和权限回调，不要为模型可调用行为读取可变全局上下文；优先使用作用域句柄（ctx.conversation、ctx.cwd、ctx.agent），并用 letta.capabilities 保护可选 UI。
主要能力：可按需注册 mod 工具、mod 命令、本地模型提供方、生命周期/工具/回合事件、权限覆盖层、面板与状态值。不同宿主加载的能力子集不同：TUI/headless 宿主可加载工具、命令、事件、UI 和提供方；desktop listener 只加载工具、命令、提供方及工具/回合事件，不加载面板 UI。每项注册都应基于其行为所依赖的全部能力做守卫。
使用方式：mod 文件默认放在 ~/.letta/mods/foo.ts（本机本地会话生效）；仅当行为需随某个 agent 的 MemFS/记忆迁移时放在 $MEMORY_DIR/mods/foo.ts。不要创建项目 mod。默认写单文件，除非用户要求更大结构。导出 activate(letta) 函数，注册时返回 disposer，并在清理函数中逆序释放提供方、命令、工具、事件、定时器、订阅和应关闭的面板。用户要求分享、发布、分发或使用第三方包依赖时，先构建可用 mod 文件，再执行 letta mods package <mod-file> --name <package-name>。完成后告知用户改动文件的绝对路径并运行 /reload；若 mod 破坏启动或命令处理，用 letta --no-mods 或 LETTA_DISABLE_MODS=1 letta 恢复。
适用场景与限制：适用于扩展本地 agent 能力，例如模型自主调用的工具、人类显式触发的斜杠命令、命令 + 面板 + 作用域会话 fork、忙碌命令（runWhenBusy: true，返回 handled 并自行处理 UI/后台）、事件反应、动态权限策略、本地 agent 自定义提供方。自定义提供方 mod 仅限本地后端/本地 agent，不能为 Constellation/云 agent 添加提供方；提供方注册需与命令/工具/UI 解耦。直接 mod 文件不应假设有第三方 npm 包，优先使用 Node/Bun 内置能力；本地 shell 执行优先 execFile/spawn 而非拼接 shell 字符串；避免启动时产生意外副作用；用户可见输出保持简短。使用 letta.diagnostics.report 谨慎报告设置/运行时问题，默认 severity 为 error。诊断文件路径为 ~/.letta/mods/diagnostics/latest.json。