jg-agent-hq
TypeScript库和本地控制器，用于运行编码代理的应用程序。创建本地Claude Code和Codex会话，发送工作，处理权限，并通过一个API跟踪结果。
使用它来构建代理仪表板、编辑器集成或自动化开发工作流。总部拥有本地会话控制权。您的应用程序拥有自己的接口、身份验证和机外备份。本地cli提供编码工具、工具、技能和登录；其他提供者可以实现相同的主机契约。
Linux或macOS需要Node.js 24.15.0或更高版本。锁协议使用POSIX所有权、私有目录和进程活动探测。Windows不在受支持的主机契约范围内。
安装
本地安装包：
npm install jg-agent-hq
npx jg-agent-hq serve --state-root .runtime --workspace-root .
分别安装Claude Code和/或Codex，并通过其本地cli登录。在您信任的工作区中运行控制器。下面的CLI示例假设安装的可执行文件位于PATH；加上前缀 npx 用于本地NPM安装。
这个公共包提供了一个本地控制器和浏览器安全的契约。应用程序拥有自己的UI、身份验证和部署。它不包括托管应用程序或Moldea UI下载。
发展
使用pnpm 12.4.0。运行 pnpm install,然后 pnpm check:package 要构建，请执行构建的API和打包的消费者，类型检查和格式检查。 pnpm test:unit 和 pnpm test:integration 在构建之后选择它们自己的类别。私人网站工作区有单独的检查；安装Chromium pnpm --dir website exec playwright install chromium，然后跑 pnpm --dir website check。 pnpm check 在两方面都有突破。
工作 development;评审的变更范围 main 通过拉请求。在两个Node检查通过之后 main， check.yml 通过npm配置的可信发布器发布经过消费者测试的压缩包，然后部署网站。不需要本地npm登录或令牌。跳过了相同的已发布版本；更改的内容需要新版本。
测试
pnpm test， pnpm check:package, pnpm check 进行必要的报道。他们的 :full 对应方保留完整的包或包/网站检查。粒度和集中的命令在默认情况下保持完整。仅在明确请求时在本地完整运行；看到 测试策略 用于分类和受影响的消费者检查。
当只有这六个聚合脚本和这个标记的测试命令块不同时，测试维护可以重用现有的版本。所有运行时文件、依赖项、导出、安装脚本、其他文档和文件权限仍然受到发布检查的保护。上述一般版本规则的这一狭隘例外跳过了出版；它不会改变已安装的包。
锁的所有权
调用者提供可信状态根。锁住它的私处 .runtime/hq.lock． 持有人记录其进程ID、nonce、安全操作标签和创建时间。等待活的持有者。已死的、不完整的或无法验证的所有者需要检查，并且永远不会自动回收，因为子进程可能保持活动状态。一个例外是运行时停止而不释放状态根：当主机的 isPreviousRuntimeStopped 检查证明该运行时的进程不存在，下一个运行时将替换其所有者记录，并移除持有者不再存在的锁和它留下的套接字。主机保证一次最多有一个调用方回收给定的状态根。
短元数据操作使用 withHqLock． 长期运行时所有权必须使用单独的所有者记录；永远不要在代理回合的生命周期内持有元数据锁。该锁协调协作进程，并且不会隔离作为同一操作系统用户运行的恶意代码。
机器范围的锁是分开的。这个 locks 阅读和 jg-agent-hq locks 列出机器上的脚本、代理和应用程序通过的已命名锁 jg-locks，每个都有它的持有者，所以HQ上的应用程序可以显示它们。总部只读取它们；它从不占用、等待或恢复一个。看到 机锁。
故意失败使用 Exception 从 jg-exception，使用错误引用中的命名字符串代码。本地客户端使用 PUBLIC_ERROR_CODES 和 PUBLIC_ERROR_MESSAGES 从 jg-agent-hq/contracts 在IPC边界翻译的错误。安全分类仍然与私人诊断原因分开。
本地控制器
安装所需的提供程序，并通过它们的本机cli登录，然后启动 jg-agent-hq serve --state-root .runtime --workspace-root /path/to/workspace。运行 jg-agent-hq status --state-root .runtime 在客户端。 threads， thread， turns， items 和 usage 读取本地信息，每个条目都带有时间 createdAt。 item-detail 读取开发人员在一个项目中检查的内容：它的命令和输出、工具调用、文件差异和图像，以及 item-image 返回其中一个图像。 stop 等待确认的运行时关闭。
Node API公开了 createAgentHq({ stateRoot, allowedRoots }) 和 requestAgentHq(stateRoot, command)． 配置来自这些受信任的操作员输入。编码指令文件不是运行时配置。
控制器拥有独立于客户端连接的SQLite工作器和本机连接。它的提供程序注册中心仅在选择时启动每个本机集成。存储和托管会话读取无需安装编码CLI即可工作；不可用的提供程序不会禁用另一个提供程序。私有状态包含生存期所有者、Unix套接字和SQLite发现元数据。 会话历史记录保存在本机存储中；总部在他们的行动收据上保留完整的有界最终结果。浏览永远不会恢复外部会话或启动推理。配额窗口来自本地帐户观察，具有显式的陈旧和不可用状态。使用读数包括食品法典信用余额和报告时可用的赚取重置计数，加上克劳德五小时和七天表及其模型/表面范围和重置时间。
使用 sessions 为了发现和 session-evidence 最新的历史证据。这些读取适合65,536个序列化字节，保留精确的本机标识和内容散列，并以UTF-8块继续读取大型主体。选择一个项目，打开或项目类型与过滤器。匹配的名称仍然是单独的会话。来源区分原生证据与确切宿主提交的证据；历史文本和引用的反馈从未获得批准。看到 有界会话证据。
受信任的节点主机可以打开由 hq.storage 并将应用程序表置于自己的前缀之下。总部储备 hq_，在启动时验证其当前模式戳，并保留应用程序模式所有权和 user_version 和主人一起。使用 hq.withStorageMaintenance(callback) 对于主机模式更改；它在回调之前耗尽已接受的工作并拒绝活动的本机执行。印章记录编写数据库的包版本，并且startup拒绝任何其他命名该版本错误的模式；HQ从不迁移存储。看到 共享存储契约。
createHqSnapshot(hq, destination) 在代理保持工作的同时，通过SQLite的备份API捕获本地状态，包括主机表和操作。钥匙，在总部状态下锁定根；主机保持自己的连接不写主机表，直到它解析。它省略了Claude转录的索引，恢复的运行时根据其第一次Claude历史读取的转录重新构建该索引，就像新运行时一样。 inspectHqSnapshot(directory) 验证完整的快照； restoreHqSnapshot({ snapshotDirectory, destination }) 验证它并将其分阶段到一个新的私有恢复工作区。 packHqSnapshot(snapshotDirectory, archivePath, key) 将快照加密为一个AES-256-GCM文件，用于机外副本 unpackHqSnapshot(archivePath, destination, key) 验证并将其作为快照目录写回。来自另一个模式的快照被编写它们的包版本拒绝。恢复本地所有权需要和解，允许的根必须明确选择。主机拥有密钥和远程备份；失败的磁盘可能会丢失自上次成功的脱机备份以来所做的更改。看到 快照和恢复 和 复苏。
会议也是在终端上开始的。共享守护进程的法典会话和克劳德会话 claude agents --json 报告一个活动状态(running， waiting， idle， closed， failed 或 unknown)与外部所有权。HQ建立在每个CLI提供的基础上，并且永远不会停止、唤醒或驱动终端运行的会话：它采用终端在回合之间通过共享守护进程保持的Codex会话，并且只有在没有终端运行它时才使用Claude会话，而Claude会话是 terminal 字段命名执行该操作的终端。被管理或观察会话的每个状态变化都按顺序记录；阅读它们 { kind: 'session-states', afterSequence } 或 session-states。 active-sessions 列出每个运行和等待会话及其工作空间， unstarted-threads 列出了HQ在他们的第一个回合之前创建的会话 observation-pace 每5秒对克劳德进行一次投票，而不是30秒，同时有客户在现场观看。看到 会话状态。
提供者id是有界的小写标识符。法典和克劳德是内置的；受信任的节点主机可以额外注册 IAgentProviderFactory 实现通过 providerFactories． 功能报告当前操作支持、提供者/会话范围和不可用原因。本机版本标签是诊断性元数据，从不决定是否允许。未知的基本控制数据显式失败。 jg-agent-hq/contracts 包含浏览器安全的模式和类型；导入它不会导入主机运行时。
使用 --provider claude 了解克劳德的历史和用法；默认值为 codex． Claude通过其本地结构化CLI惰性连接，启用了正常设置，没有用户提示。历史读取仅在运行时第一次检查CLI时启动该进程，并且使用结果将在60秒内响应读取。使用请求显式禁用可选的转录行为扫描。 它的本地历史读取器验证所需的身份、工作空间和链字段，允许添加字段和混合版本标签，在SQLite中保留字节位置而不是会话主体，并且不会为未更改的记录写入任何内容。历史记录、活动项和证据以CLI显示的方式呈现项 notice 项，工具调用与其结果配对，以及每个文件更改的文件；未知排序的内容表示为不受支持，不可信的标识或排序使受影响的读取不可用。文件历史记录无法建立当前执行状态。看到 读者限制和新鲜度收缩。
明确的动作创建、命名、采用、恢复和关闭线程；发送空闲消息；精确地转向；将下一条消息排队；中断;并回答本地问题，许可或MCP引出。操作具有稳定的uuid和持久的收据。 action-wait 一旦它有了自己的本地线程ID，或者被HQ自己的更改而不是轮询唤醒，或者当它的超时时间（最多30秒）过去时，它就会返回收据。重复相同的请求返回其收据；更改UUID的有效负载冲突。丢失的确认将保持不确定状态，直到确切的本地响应到达或操作人员做出明确的恢复选择。总部从不重新发送不确定的输入。
操作还将本机历史拆分为一个单独的会话，压缩空闲会话，并在支持的情况下使用本机存档/解存档和历史还原。福克斯保留了确切的本土血统。在显式恢复之前，取消存档将使会话处于非活动状态。恢复更改会话记录；它不撤销文件。Claude公开压缩和分叉，而归档和会话恢复报告为不支持。
使用 account --provider <id> 对于安全的本地帐户元数据，和 mcp-servers --thread-id <id> 查看已配置的服务器状态。 mcp-tools 和 mcp-resources 选择 --server-name <name> 并且支持有界延拓。本机重新加载和身份验证控件使用现有的JSON request 接口和持久操作收据。登录url是实时呈现的，永远不会保存在SQLite中。看到 本地帐户和扩展。
使用 models --provider <id> 对于本地模型和工作选择，和 configuration --provider <id> --workspace-root <path> [--thread-id <id>] 对于已知的有效设置和分页本机代理/配置文件元数据。创建和显式恢复接受键入的启动设置；消息可以为下一个回合选择一个模型和工作。启动指令、本机Claude代理和权限设置需要空闲会话重新启动。能力模式描述支持的选择和更改模式。未知的设置仍然是显式的，本地配置文件保留在每个CLI中。看到 配置合同。
本地执行设置、指令、技能和工具权限保留在每个CLI中。Claude在每个受控会话中使用自己的结构化进程，在空闲60分钟后关闭它，并在下一次输入时重新打开它，并使用结构化用户消息来引导其活动回合。在确认采用、恢复或恢复之前关闭其他CLI控制器。总部协调共享一个状态目录的会话；它不能锁定独立运行的本机cli。 集成浏览器主机可以通过编程API使用持久的主机-操作许可和操作符范围的协调；看到 浏览器主机契约． 独立的CLI只发布它实现的命令。
审批读取在重新连接或重新启动后返回索引的、游标分页的挂起、应答的和过期的元数据。敏感表示仅在准确的本机请求存在时可用。本地权限需要显式响应；未知的请求类型或范围被拒绝。看到 本地回复和重新连接读取。
持久状态包括 action.key，它必须保持私有，并与其SQLite数据库一起使用。保存排队的未交付输入和完整的有界最终结果；普通的输入主体和问答则不是。
文本和技能输入可以根据路径和媒体类型附加多达8个工作空间文件，总共16 MiB，每个文本文件256 KiB。HQ在排队交付之前再次验证它们的内容哈希值。输出模式使用原生Codex回合参数或Claude的结构化会话标志；重新连接后，所选收据上的完整验证结果和已知令牌使用情况仍然可用。实时预览保持有界并显式标记截断。看到 文件输入和完成结果。
使用 suggest-thread-name --topic "Build usage" --state-root <directory> 用于可编辑标签和 managed-thread-name --name build-usage --state-root <directory> 来解决它。当名称被占用时，“创建”将添加一个简短的序号后缀。操作和关系保留不可变的id。
使用 skills --workspace-root <directory> --state-root <directory> 要浏览本机技能目录，在该文件夹中启动的会话将具有 --provider (默认 codex)，并添加 --thread-id <id> 用于受控会话自己的目录。 skill-preview --thread-id <id> --skill-id <id> --arguments "auto exact-plan" --state-root <directory> 显示准确的调用而不发送它。缺失的本机元数据显式不可用。CLI加载所有技能内容，并保留其权限和调用规则。
使用 jg-agent-hq request --state-root <directory> 在stdin上有一个封闭的HQ命令，用于操作和控制读取。这个 API参考 描述动作信封、收据和重新连接读取。
源的例子
遵循 完成会话演练，并提供可复制的来源及其结果。
examples/control-session.ts 创建一个本机会话并读取其实际交付、输出、许可和使用观察。
这些完整的TypeScript示例使用了公共客户端和契约。启动本地控制器并首先登录到本机cli。主机提供实际的用户决策，并保持本地权限处理独立。在提交请求前保留请求的身份；在中断客户端呼叫后，检查这些收据，而不是重新运行整个示例。例如开发源，而不是包导出或自动网站操作。
examples/shared-storage.ts 使用受信任的Node运行时在app_前缀下保存单个应用程序首选项，捕获和检查共享SQLite存储，并在离线恢复后验证值。它关闭自己的SQL连接并保留主机的user_version。选择不存在的输出目录，并首先暂停所有其他写入器。应用程序在捕获前写提交；以后的备份失败不会回滚。恢复的状态在执行之前仍然需要显式的允许根。
这个 资格矩阵 记录本机行程、主机覆盖范围和剩余接口限制。
项目蓝图
src/index.ts：显式的公共包边界。examples/：用于会话和共享主机存储的公共源代码助手。src/locks/：锁的所有权、获取、状态和有意恢复。src/runtime/：可信配置和终身所有权。src/ipc/和src/cli/：私有本地命令和已安装的可执行文件。src/providers/codex/：共享的应用服务器守护进程连接、本地历史记录和帐户协议。src/providers/claude/：本机结构化控制和使用，身份验证，工作人员拥有的本地历史阅读器，活动会话轮询和后台任务计数器，它读取成绩单。src/providers/registry/惰性工厂、规范化的提供者证据、有界生命周期和源隔离。src/providers/inputs/和src/providers/results/：检查文件交付和完成本机结果验证。src/providers/configuration/和src/providers/lineage/有限的本地选择和确定的不可变会话关系。src/sessions/：具有实时会话状态、活动会话列表、有界证据和来源、游标绑定历史读取和短标签建议的授权发现。src/skills/：有界本地编目、调用预览和显式输入准备。src/accounts/和src/extensions/：安全的账户观察和授权，有界的本地MCP库存。src/actions/：持久的动作调度，本地输入路由，有界的实时表示和接收等待自己的变化唤醒。src/store/SQLite发现元数据，观察到的会话和状态转换，动作/控制分类帐和快照的数据库副本在一个worker中。src/storage/：可信主机元数据、独占维护和当前模式戳。src/snapshots/：在代理工作时捕获，清单验证和释放本机所有权的离线恢复。src/contracts/浏览器安全的命令和响应契约，包括jg-locks锁列表。scripts/package/：构建输出清理和打包消费者检查。scripts/release/：注册表版本/完整性检查和测试存档的可信发布。scripts/test-support/：一次性外部CLI固定装置。vitest/：分离单元和集成选择。api/README.md：规范的公共API引用。errors/README.md：稳定应用错误。website/：私有的公共站点工作区，带有自己的README和测试/检查命令；规范文档主体保留在这个根README和api/README.md。docs/website.md：持久的网站架构，验证和生成的资产来源。docs/architecture.md：提供程序和数据库所有权、模式初始化和主机维护。docs/recovery.md：本地快照覆盖，离线恢复和主机的远程持久性责任。
/docs 保留用于简洁，快速扫描的基本持久概念和过程的文档。API引用保持在外部 /docs。
测试
测试使用构建的公共输出。单元测试涵盖应用程序拥有的决策；集成测试使用真正的临时文件、SQLite工作线程、IPC、子进程和一个孤立的tarball消费者。合成的cli只替换外部提供者边界。每个fixture移除自己的资源。生产输出排除所有测试类别。 pnpm test 构建，然后运行单元和集成套件。 pnpm check:package 是任务完成检查。使用Vitest's连续运行更改的集成文件三次，禁用重试 --repeats=2 --retry=0。
该网站的README和 docs/website.md 定义它的一次构建检查组合、特定于类别的脚本和拥有的预览/浏览器生命周期。当工作空间配置或规范站点内容发生更改时，必须同时通过根检查和网站检查以完成任务。
运行时fixture拆卸会向测试运行器和回调程序注册，因此测试超时不能在下一个测试期间恢复环境变量。
当前本地检查仅建立被测试的主机。发布资格必须包括Node引擎层和当前LTS；macOS操作需要自己的运行时证据。