Uh oh!
There was an error while loading. Please reload this page.
feat(extensions): add agent-authored Tool and UI packages - #3003
Conversation
ARE404
left a comment
There was a problem hiding this comment.
Reviewed against the repository standards and the invariants in #2973. The existing build and test suites pass (@maka/runtime: 2827/0, @maka/runtime-host: 931/0), but the inline findings below expose security and lifecycle cases not covered by those tests. Please also restore the required PR-template checklist and obtain an independent human review before merge, as required by CONTRIBUTING.md. This is submitted as a COMMENT review while the PR is still a draft.
| env: workerEnvironment(), | ||
| profile: workerProfile(this.packageRevision.manifest), | ||
| pathContext: { | ||
| workspaceRoots: [canonicalCwd], |
There was a problem hiding this comment.
[P1] Keep installed revisions read-only during health checks. healthCheck() passes packageRevision.root as cwd, and this mapping turns that directory into :workspace_roots. A package requesting workspace: write can therefore rewrite its own entry during health check; later invocations still identify and import it under the original SHA revision. Please use a neutral/session workspace for health checks and expose the package root only as read-only runtime input.
| description: | ||
| 'Activate, update, stop, or delete a Tool package for the current session. Activation persists with the session until stopped.', | ||
| parameters: manageInput, | ||
| categoryHint: 'file_write', |
There was a problem hiding this comment.
[P1] file_write understates what activate/update does. Controller convergence imports the package and executes its health check under the manifest-requested workspace/network sandbox, so arbitrary package code can run after only a file-write approval. Please split these operations or gate them with an execution category/facts that reflect the package manifest, like test_tool does.
| return { | ||
| kind: 'enable', | ||
| bindingId: requireEntityId(input.bindingId, 'extension bindingId'), | ||
| scopeId: requireEntityId(input.scopeId, 'extension scopeId'), |
There was a problem hiding this comment.
[P2] This protocol decoder uses generic requireEntityId, whose grammar rejects . and :, while the canonical extension/scope validators intentionally allow dotted extension IDs and dotted/colon scope IDs. For example, the supported dev.maka.calculator package can be installed internally but fail external response decoding. Please use the shared extension/scope identity validators consistently in every input and projection decoder.
| throw error; | ||
| } | ||
| const resolveModelTools = (): readonly MakaTool[] => | ||
| input.extensions?.resolveTools(input.context.sessionId, modelComposition.tools, { |
There was a problem hiding this comment.
[P1] Extension tools are appended after createInteractiveRunComposer has already applied the final Plan, Deep Research, hosted-profile, permission, and product filters. This can re-expose extension tools in modes where the final composition deliberately removed tools. Please feed contributions into the canonical composition/filter pipeline rather than appending them afterward.
| sourceRevisions: resolved.sourceRevisions, | ||
| baseSystemPromptHash: stableHash(resolved.text ?? ''), | ||
| toolCatalogHash: toolCatalogHash(modelComposition.tools), | ||
| toolCatalogHash: toolCatalogHash(tools), |
There was a problem hiding this comment.
[P1] A catalog hash plus tool names/schema hashes does not pin the exact extension revision used by an admitted Run. Two revisions with identical schemas are indistinguishable, and update/stop can retire the activation referenced by the current send snapshot. Please persist the extension ID/revision (or a canonical composition digest) and retain those revisions until the Run reaches a terminal state so recovery can reproduce the exact composition.
| export class ToolPackageStore { | ||
| readonly root: string; | ||
| constructor(controlDirectory: string) { |
There was a problem hiding this comment.
[P1] Agent-authored packages are stored in the Host-global control directory without session/owner identity. define_tool and inspection also do not bind ownership, so another session can discover and activate the package, and session disposal does not remove it. #2973 calls for the initial agent-authored surface to be session-scoped; please persist/enforce ownership and clean it up with the owning session.
| ): Promise<ExecutionRuntimeHostComposition> { | ||
| const stores = await openInteractiveExecutionStoresForWrite(context.owner.lease); | ||
| await stores.sessionStore.ready(); | ||
| const extensions = new HostExtensionRuntime(); |
There was a problem hiding this comment.
[P1] The production registry is created without protected core tool names. A package declaring Read, manage_tool, or another protected name can therefore install and activate successfully; the conflict is discovered only during a later model composition, after the binding has been persisted. Please reject protected-name conflicts before the activation commit and construct the production registry with the authoritative core-name set.
| .find(({ name }) => name === input.toolName); | ||
| if (!tool) throw new Error(`Active session Tool was not found: ${input.toolName}`); | ||
| await validateArgs(tool, input.args); | ||
| return tool.impl(input.args, context); |
There was a problem hiding this comment.
[P2] Calling tool.impl() directly bypasses the contributed tool's canonical Tool Runtime path, including its own permission category, recovery mode, durable settlement/identity, and product routing. invoke_tool should dispatch through the same stable Tool Runtime bridge used by normal model tool calls.
| const [program, ...args] = transformed.exec.argv; | ||
| if (!program) | ||
| throw new ToolPackageWorkerError('sandbox_unavailable', 'Sandbox launch is empty'); | ||
| const child = spawn(program, args, { |
There was a problem hiding this comment.
[P2] The worker has wall-time and output bounds, but this launch has no explicit heap/CPU/process-count limit. A package can exhaust Host memory or create child processes before the timeout, which does not meet #2973's resource-limited requirement. Please add bounded Node heap and sandbox-level CPU/process limits, including descendants.
xxhZs
commented
Aug 15, 2026
Test case: website → Graph-authored presentation → restored Maka UIThis prompt-driven E2E validates the complete dynamic capability loop with a real source page: Building effective agents. Flow
Result
The 52.4-second video below is an accelerated summary of the original continuous 478.7-second audit recording; no successful or recovery stage was omitted. Demo videomaka-graph-ppt-52s-demo.mp4Simplified flow |
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Comment |
M4n5ter
left a comment
There was a problem hiding this comment.
English
Thanks for building this out. I reviewed the implementation against #2973 and the current multi-Host Runtime Host architecture.
The lifecycle kernel, typed contribution registries, content-addressed packages, out-of-process Tool workers, and fixed extension Domain Module are solid foundations. However, I do not think the unified Tool/UI plugin platform is ready to merge in its current form. The following are blocking:
UI ownership conflicts with the multi-Host Desktop architecture.
UI selection uses one Host-owneddesktop-uiscope,ui-extension-frame-protocol-main.tskeeps one module-globalactiveClient, and anapp.rootcontribution may replace the entire Desktop. The current Desktop keeps multiple Hosts connected and identifies Sessions by(hostId, sessionId), so one State Root cannot authoritatively own a Client-global root. The frame URL and bridge also lack Host identity. UI package selection, safe mode, and root/slot state should be Client-owned; Host-linked contributions must be explicitly scoped byhostId/targetEpoch. I also recommend keeping the official root protected initially and starting with slots/overlays, as proposed in #2973.An admitted Run is not pinned to an exact Extension Composition.
execution-model-composition.tsappends Extension Tools after the canonical collaboration/product filters. The durable Run Composition records Tool names and schema hashes, but not Extension IDs, revisions, or the Extension composition digest. Two revisions with identical schemas but different implementations are therefore indistinguishable. In addition, update/stop can retire an activation already referenced by an in-flight send, causing a later Tool call from that Run to fail asretired. Please resolve Extensions before the final Tool filtering pipeline, persist the exact revision composition at Run admission, and hold activation leases until the Run reaches a terminal state.Health checks can mutate their own immutable revision.
ToolPackageActivation.healthCheck()usespackageRevision.rootas bothcwdand:workspace_roots. A package declaringworkspace: writecan modify its installed entry or add files while being imported for health checking, while the health check itself still succeeds. I reproduced this with a fault-injection test: the package wrote into its content-addressed revision, and only a laterstore.load()detected the hash mismatch. Health checks need a dedicated scratch cwd and a read-only package mount.Binding and Configuration persistence is not atomic.
HostExtensionController.#persist()commits the Binding document before the Configuration document. I reproduced a case where the first write succeeded and the second failed: the enable operation returnedpersistence_failedand did not activate immediately, but after Host restart the persisted Binding was recovered and activated. This is an unreported partial commit. Binding plus Configuration need one transactional authority, or at minimum this path must becomecommit_outcome_unknownand drain the Host.Session-scoped Extension ownership is not connected to Session retirement.
manage_toolpersists bindings under the Session ID, butHostSessionRetirementCoordinatorhas no Extension retirement participant, and production code never callsdisposeScope()for a removed Session. The binding and registration can therefore survive Session deletion and Host restart, retain revisions indefinitely, and become ownerless. Agent-authored packages are also globally discoverable by other Sessions. Immutable blobs may be globally deduplicated, but ownership/reference authorization and cleanup need to follow the owning Session or revision family through the durable retirement pipeline.The permission and isolation boundary is still incomplete.
manage_toolandmanage_uiare categorized asfile_write, although activation/update can execute package health code and enable network access, Host methods, or the complete Session bridge.invoke_toolstill callstool.impl()directly instead of using the canonical Tool Runtime path. Production also does not provide authoritativeprotectedToolNames, so Core-name conflicts may be committed and discovered only during later model composition. Finally, workers have wall-time/output limits but no explicit heap, CPU, or process/descendant limits.
Most of these align with still-unresolved inline review threads. The earlier identity-decoder issue appears fixed, but the outdated invoke_tool thread remains semantically applicable because the new code still invokes the implementation directly.
Validation performed on head f007f70f1:
- full repository build passed;
- 45 focused Extension/Tool/UI tests passed;
- fault injection reproduced both the revision self-mutation and partial persistence commit;
- merging current
mainproduces five direct conflicts, including Desktop root, Run composition, AI SDK, and UI navigation; - the PR is still draft/
DIRTY, with no current usable CI result.
I recommend splitting this into independently reviewable phases: lifecycle kernel, Host-owned trusted Tool slice, exact Run composition and leases, Session-owned agent authoring, and then a separate Client-owned UI Extension proposal. The current implementation should not be approved as the final Runtime Host plugin architecture.
中文
感谢完成这套实现。我按照 #2973 以及当前 multi-Host Runtime Host 架构，对代码进行了审查。
Lifecycle Kernel、类型化 Contribution Registry、content-addressed package、进程外 Tool Worker，以及固定的 extension Domain Module 都是很好的基础。不过，目前这套统一 Tool/UI 插件平台还不适合合入，以下问题属于阻断项：
UI 所有权与 multi-Host Desktop 架构冲突。
UI 选择依赖一个 Host-owneddesktop-uiscope，ui-extension-frame-protocol-main.ts只有一个模块级activeClient，同时app.rootContribution 可以替换整个 Desktop。当前 Desktop 会同时连接多个 Host，Session 身份是(hostId, sessionId)，因此单个 State Root 不应拥有 Client-global root。Frame URL 和 bridge 也没有携带 Host 身份。UI package 选择、safe mode、root/slot 状态应由 Client 管理；与 Host 关联的 Contribution 必须显式使用hostId/targetEpoch。同时建议遵循 #2973，初期保护官方 root，只开放 slots/overlays。已经 admission 的 Run 没有固定到 exact Extension Composition。
execution-model-composition.ts在标准 collaboration/product Tool 过滤完成后才追加 Extension Tools。持久化的 Run Composition 只记录 Tool 名称和 schema hash，没有记录 Extension ID、revision 或 Extension composition digest，因此两个 schema 相同但实现不同的 revision 无法区分。另外，update/stop 可以 retire 已经被进行中 send 引用的 activation，导致该 Run 稍后调用 Tool 时收到retired。Extension 应在最终 Tool 过滤前参与组合，在 Run admission 时持久化 exact revision composition，并持有 activation lease 直到 Run terminal。健康检查可以修改自己的 immutable revision。
ToolPackageActivation.healthCheck()同时把packageRevision.root用作cwd和:workspace_roots。声明workspace: write的 package 可以在 health check import 阶段修改已安装 entry 或添加文件，而健康检查本身仍然成功。我通过故障注入复现了这一点：package 成功写入 content-addressed revision，直到之后调用store.load()才检测到 hash mismatch。健康检查必须使用独立 scratch cwd，并且 package root 必须始终只读。Binding 与 Configuration 持久化不是原子的。
HostExtensionController.#persist()先提交 Binding 文档，再提交 Configuration 文档。我复现了第一步成功、第二步失败的情况：enable 返回persistence_failed，当下也没有激活，但 Host 重启后会恢复已经提交的 Binding 并自动激活。这是一个未被报告的 partial commit。Binding 与 Configuration 需要一个事务性权威；至少该路径应返回commit_outcome_unknown并 drain Host。Session-scoped Extension ownership 没有接入 Session retirement。
manage_tool使用 Session ID 持久化 Binding，但HostSessionRetirementCoordinator没有 Extension retirement participant，生产代码也不会在 Session 删除时调用disposeScope()。因此 Binding 和 registration 可以在 Session 删除及 Host 重启后继续存在，永久占用 revision，并失去 owner。Agent-authored package 也可以被其他 Session 全局发现。Immutable blob 可以全局去重，但 ownership/reference authorization 和清理必须跟随所属 Session 或 revision family 进入持久化 retirement pipeline。权限和隔离边界仍未闭合。
manage_tool和manage_ui只被归类为file_write，但 activate/update 会执行 package health code，并可能启用网络、Host methods 或完整 Session bridge。invoke_tool仍直接调用tool.impl()，没有经过标准 Tool Runtime。生产环境也没有提供 authoritativeprotectedToolNames，因此 Core Tool 名称冲突可能先被提交，之后才在 model composition 阶段暴露。Worker 虽然有 wall-time/output 限制，但没有明确的 heap、CPU、process/descendant 限制。
这些问题大多与当前尚未解决的 inline review thread 一致。之前的 identity decoder 问题已经修复；不过 invoke_tool thread 虽然因为代码移动显示为 outdated，其问题仍然存在，因为新代码依然直接调用 implementation。
我在 head f007f70f1 上完成了以下验证：
- 全仓 build 通过；
- 45 个 Extension/Tool/UI 聚焦测试全部通过；
- 故障注入稳定复现了 revision 自修改和持久化 partial commit；
- 合并当前
main会产生 5 个直接冲突，涉及 Desktop root、Run composition、AI SDK 和 UI navigation； - PR 仍是 draft/
DIRTY，目前没有可用的最新 CI 结果。
建议将其拆成可独立审查的阶段：Lifecycle Kernel、Host-owned trusted Tool vertical slice、exact Run composition 与 activation lease、Session-owned agent authoring，最后再单独提出 Client-owned UI Extension 设计。当前实现不应作为最终 Runtime Host 插件架构获得批准。
M4n5ter
commented
Aug 17, 2026
EnglishOne architectural addendum after comparing this design with DeepSeek Harness and Cordis: The current implementation is not literally “insert-only”: it exposes The missing distinction is between:
Today, Cordis addresses the mount/unmount symmetry by giving every loaded plugin instance a first-class Harness applies those primitives to agent-authored dynamic Plugins with explicit paired operations: I recommend making the equivalent distinction explicit in Maka: Concretely, this likely requires:
I would not copy Cordis wholesale. Its generic Loader removal starts Fiber disposal without awaiting it, while Runtime Host teardown should follow Harness’s stricter “dispose reaches quiescence” rule. Harness’s dynamic packages are also process-local, non-durable, and explicitly not protected by a true sandbox boundary. Maka still needs its protected Host kernel, durable reference accounting, permissions, and out-of-process isolation. In short: the PR has removal APIs, but it still needs admission leases, ownership-driven teardown, and revision GC before Extensions can be considered safely hot-unpluggable. 中文在对照 DeepSeek Harness 和 Cordis 后，再补充一个架构层面的意见： 当前实现并非字面意义上的“只能插、不能拔”：它已经提供 当前缺少的是对以下阶段的明确区分：
现在的 Cordis 通过为每个已加载插件实例建立一等 Harness 在此基础上为 agent-authored dynamic Plugin 提供了成对操作： 建议 Maka 也明确建立对应的状态模型： 具体可能需要：
不建议完整照搬 Cordis。它的通用 Loader remove 会启动 Fiber disposal，但不会等待其完成；Runtime Host 应采用 Harness 更严格的“dispose 必须达到 quiescence”契约。Harness 的 dynamic package 也是进程内、非持久化的，并明确不具备真正的 sandbox 安全边界。Maka 仍然需要受保护的 Host kernel、durable reference accounting、权限控制和进程外隔离。 简而言之：这个 PR 已经有 removal API，但在补齐 admission lease、ownership-driven teardown 和 revision GC 之前，还不能认为 Extension 真正支持安全热拔。 |
me2seeks
commented
Aug 17, 2026
Really like the observe-mode core events — One gap I hit while wiring Maka into herdr: Would a |
Summary
app.rootUI Revision instead of reserving a fixed Maka workspace or panellist/send/stop) without exposing credentials, filesystem authority, preload APIs, or arbitrary host accessinputSchemafrommanage_toolactivation/update so an Agent can invoke the visual Tool without guessing its contractArchitecture boundary
Maka owns the framework: window bootstrap, Extension Store/Binding lifecycle, immutable Revision admission, typed bridges, isolation, state authority, fallback, and recovery. Maka does not own the installed visual layout.
The user/Agent Extension owns the complete visible root: navigation, layout, conversation composer, visual Tool surface, art direction, and responsive behavior. Replacing or disabling that Revision removes the whole custom UI together; the compiled official UI is only the trusted fallback snapshot.
Maka remains one runtime and one repository. Tool and UI scripts are external Extension artifacts, not separate services or linked application libraries.
Graph workflow
Main plans -> subagents author/test candidates in parallel -> Main validates/activates/invokes -> Main rejects defects and dispatches repair nodes -> independent tools cross-check the result.
The warehouse-location Graph scenario completed with 7 define calls and 8 test calls from child sessions, plus 6 activation and 6 invocation calls from the Main session. No forbidden shell, file-editing, or direct-web tools were used.
Verification
app.root+project_plan_commitRevision: 3 model requests, onemanage_tool, oneinvoke_tool, then the complete UI committed 6 tasks and 4 risksPart of #2973.