Skip to content

Commit 1f30be1

Browse files
feat(objectql)!: a tool holds one name per package (bare-name one holder, after the AI family) (#31661)
<!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9T7XkgYLhpd9ZEZyjhEBoYV)_ Fixes #31414 `tool` joins the bare-name one-holder list after the AI family of #30803 (PR #31375), by the maintainer's acceptance of a separate card for it. Claim 6725057016 (`domain:server#1`, card-thread session_01ADHkmS1DVx9CH1xvXikQBW). Clause-②: no (narrowing) — measured on head `30b6c84f` and, for base `69244406`, by the ablation that puts base's list back: the engine's package door (`SchemaRegistry.installPackage`) and item seam (`SchemaRegistry.registerItem`) refuse, after the cold boot, a package registration they accepted on base: one whose tool bears a name another installed package holds (base list: `install-local` answers `200` and the tool is shadowed; head: `422 PLUGIN_REGISTER_FAILED`). Nothing is widened. Metadata-protocol: narrowed Skills-docs: none — `skills/**` does not teach that two packages may share a tool name (grep: zero hits), and the naming rule itself is phase 2's (#30805); the prescription ships in the refusal and warning text and in ADR-0048's dated note P1.10. ⚠️ **Tier H**: this diff touches `docs/adr/0048-cross-package-metadata-collision.md` (a new dated note, P1.10, under the 2026-11-06 addendum, and `tool` named in the header's Addenda entry, §3.4's 2026-11-06 note, P1.5 and P1.9; ⛔ not the Status line, which draft PR #31586 edits). The seat routes the approver. ## 维护者速读 - 改了什么:`tool` 加入"一个名字只认一个包"的列表(排在 agent、skill 之后)。冷启动结束后,第二个包再声明同名 tool,安装门和注册口都拒绝,返回 422 `NAMESPACE_CONFLICT`,点出两个持有包和改名建议;已经同名的部署照常启动、只告警一次。 - 为什么改:tool 的所有读者都只按裸名找它:`/meta/tool/NAME` 返回先注册包的那个;skill 的 `tools` 列表只能写裸名;MCP 服务器一个名字只能注册一个 tool;tool 调用协议里没有包。所以两个同名 tool 必然有一个被静默遮蔽。 - 风险与回滚:只收窄接受集,不改已存数据;示例应用和平台包都没声明 tool,现有部署不会启动失败(冷启动只告警)。回滚即 revert 本 PR。 - 先看:`packages/objectql/src/bare-name-one-holder.ts`(列表末尾加 `tool` 及其理由短句)、ADR-0048 P1.10、`registry-bare-name-one-holder-ai-family.test.ts`。 - 两分钟验证:`pnpm --filter @objectstack/objectql exec vitest run src/registry-bare-name-one-holder-ai-family.test.ts` —— 预期 38 passed。 - 需要你做的:ADR 改动是 Tier H,需要审批人批准后由席位落地。 ## What changes - **`packages/objectql/src/bare-name-one-holder.ts`** — `tool` joins `BARE_NAME_ONE_HOLDER_TYPES` last, after the AI family (`BARE_NAME_REGISTRY_TYPES` stays derived): its collection key (`tools`), consumer clause ("a skill's `tools` and an MCP client name a tool") and noun, empty built-in and overridable-baseline sets. Module doc: the measurement. - **`packages/objectql/src/registry.ts`**, **`packages/objectql/src/plugin.ts`** — comments name `tool` among the covered types; no code change. Both doors and the cold-boot seal are generic over the list. - **`packages/objectql/src/registry-bare-name-one-holder-ai-family.test.ts`** — `tool` runs through the AI family's matrix (it is the shared harness for these types). Forced edits, named: the whole-list cell now ends in `'tool'`; the `declaredBareNames` cell's "a tool declares nothing" now asserts tools declare (nested plugin included); the CONTROL "two packages' tools under one name both install after the seal" is replaced, since that is now the refused case, by CONTROLs for different tool names across packages, a tool versus another package's skill or agent under one name, and one package's skill and tool under one name. - **`packages/qa/dogfood/test/bare-name-one-holder-ai-family.dogfood.test.ts`** — forced edits, named: the cold-boot cell asserted the warning never names the tool; it now asserts it does (with its rename) and that `/meta/tool/NAME` keeps serving `alpha`; the CONTROL `epsilon` installed the shared tool name and now declares a fresh one. New: `install-local` of `zeta` declaring the held tool name is `422 PLUGIN_REGISTER_FAILED`. - **`docs/adr/0048-cross-package-metadata-collision.md`** (Tier H) — new dated note **P1.10 (2026-11-08)** under the 2026-11-06 addendum: the measurement (this repo's readers and the cloud reading), what is refused, the cold boot. `tool` is also named in the header's Addenda entry, §3.4's 2026-11-06 note (and dropped from its "keeps §3.4" list), P1.5 and P1.9's "Not in the list" (seat ruling B on the claim, restated 6726705019). The Status line is untouched. - **`scripts/adr-anchors/packages__objectql__src__bare-name-one-holder.ts.json`** — the invariant names `tool` after the AI family. - **`.changeset/31414-bare-name-tool.md`** — `@objectstack/objectql` `minor`, both declaration lines (the first restated `no (narrowing)` per the seat's ruling), BREAKING Why / Before / Now / The cold boot / Who moves / Unchanged, `adr-0087: not-required (no-migration-prescription)`, measured producers. ## Why (measured) Step 1 of the card, how a tool is resolved by name. No cloud read access in this container (attaching `objectstack-ai/cloud` was refused), so the cloud question went to `repo:cloud#3` on mailbox #31366 (seat's comment 6725074004), answered on the card (6725094995, read at cloud `ba6f0fa`). Both sides: | Reader | Where | Package context | |:--|:--|:--| | `GET /meta/tool/NAME` | protocol by-name read | none: first-registered package's tool, silently, either order; a third package after the boot installs `200`, shadowed (PR #31375 table, re-pinned here by the dogfood file) | | a skill's `tools` list | `packages/spec/src/ai/skill.zod.ts` `SkillSchema.tools` | none: the regex admits a bare snake_case name only; "bound by the cloud agent runtime" | | AI tool definition / tool call | `packages/spec/src/contracts/ai-service.ts` `AIToolDefinition`, `ToolCallPart` | none: `name` / `toolName`, no package member | | MCP bridge | `packages/mcp/src/mcp-server-runtime.ts` `bridgeTools`, `registerToolFromDefinition` | none: `server.registerTool(tool.name, …)`, `execute({ toolName: tool.name })`; the MCP SDK throws `Tool NAME is already registered` on a second name | | agent guardrail | `packages/spec/src/ai/agent.zod.ts` `guardrails.blockedTopics` | none: exact match on the tool name | | cloud chat (`skill.tools`) | cloud `packages/service-ai/src/skill-registry.ts#SkillRegistry.flattenToTools` | none: bare-name lookup in the tool registry (6725094995) | | cloud MCP door, direct execute | cloud `service-ai-studio` `mcpDoorSource`, `tool-routes.ts` | none: the same bare-name `ToolRegistry` map (6725094995) | The card's rule: if any consumer reads by bare name, `tool` joins. Every one does, on both sides, so it joins. One nuance from the cloud reading, recorded in P1.10: cloud's runtime executes from its in-process `ToolRegistry`, filled by plugins in code, and mirrors those into `tool` metadata for Studio; a package-declared `tool` item reaches no handler there. So on cloud this refusal keeps `/meta/tool/NAME` (what Studio shows) and every bare-name reference unambiguous; it does not touch the registry's own last-wins `set`, which is cloud code (see Acceptance notes). **Responsibility** (the claim asks which change let a second same-named tool install): no change regressed it. `tool` was never covered: ADR-0048 §3.4 retired the per-item cross-package throw for every type, and phase 1's ruling list (#30803) did not name `tool`, so PR #31375 (`4a3b186c`) recorded it as "not in the list" and pinned its coexistence as a CONTROL. **Epic #31527 / child R (#31575).** This change needs nothing from R: it adds `tool` to phase 1's refusal, which the epic's red line keeps in force until a type's own retirement child. R's package-scoped resolution would later be what lets a type leave the list. ## Verification Two heads. The feature commits (`ff31f6f9`, `57fd18f8`, `0c19dbb4`: the last only the ADR note's text) were cut on base `69244406`; `main` then moved 13 commits, one of them under `packages/objectql/src/registry.ts` (#31614), so `origin/main` was merged once at `cbd8c5b2` (no conflict). Round 2 (`30b6c84f`, on top of it) changes only the ADR text, the anchor's invariant and the changeset's declaration line; no source or test file. The delta against `origin/main` is the 8 files above. The source-level runs below are on `cbd8c5b2`, whose source and tests are byte-identical to `30b6c84f`; the gates and the three suites the seat asked for ran on `30b6c84f`: - Unit, `packages/objectql/src/registry-bare-name-one-holder-ai-family.test.ts`: **38 passed** (was 26). With the data, request and flow families' files and `hook-binder.test.ts`: **5 files / 192 passed**, on `57fd18f8` and again on `cbd8c5b2`. - Dogfood, the four bare-name files (booted showcase + `AppPlugin` packages + `MarketplaceInstallLocalPlugin`): **4 files / 17 passed** (`ff31f6f9`). - Ablation on `57fd18f8` (committed first; `ablation-replace.mjs`, marker `ABL31414`: `tool` filtered out of `BARE_NAME_ONE_HOLDER_TYPES`) → unit file **10 of 38 red** (the list and `declaredBareNames` cells; for `tool`: the package door, the ABLATION cell's after-seal half, the item seam, the nested plugin, the cold-boot warn, reload/third-package and `'refuse'` cells; the reason cell). The 28 green: every agent and skill cell, the tool's same-package reload, uninstall and environment CONTROLs, the four CONTROLs. objectql rebuilt with the mutation (`ablation-dist-preflight`: marker in 4 built files; DTS failed on the mutated literal's type, TS2322, after the JS bundles were written) → dogfood AI file **2 of 5 red**: the cold-boot line did not name `the tool "qa_shared_tool"`, and `zeta` installed (`200`). Restored (blob == HEAD, `git diff HEAD` empty), rebuilt, `--absent`: marker absent from all 14 built files, tree clean. - Consumer suites under `os-verify-lock`, every `VERDICT command-exit 0`. On `30b6c84f`: metadata-protocol **327 passed, 4 skipped / 22593 passed, 26 skipped**, rest **394 / 7546 passed, 332 skipped**, runtime (`--project local`) **562 / 9021 passed, 19 skipped**. On `cbd8c5b2` (same source and tests): `pnpm --filter @objectstack/objectql typecheck`; objectql full suite **571 files / 11593 tests**; mcp **60 / 915**; `pnpm --filter @objectstack/dogfood exec tsc --noEmit`. (All five also green on the pre-merge `57fd18f8`.) - `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` at `30b6c84f`: 90 derived families (the anchor file under `scripts/` adds seven to `cbd8c5b2`'s 83), each run with its exit captured before any pipe, all 90 exit 0. `--ran`: "90 derived famil(ies) accounted for — 90 run, 0 NOT-MEASURED" (exit 0). `node scripts/check-adr-anchors.mjs` exit 0. (The plugin-teardown self-test's pinned fixture was fetched first, `git fetch --depth=1 origin 621a487…`, a shallow-clone prerequisite.) - eslint `--no-inline-config` over `packages/objectql/src` and the dogfood file: exit 0, no findings (neither package has a `lint` script). - Full dogfood battery (`pnpm --filter @objectstack/dogfood test`, under `os-verify-lock`) at `cbd8c5b2`: `VERDICT command-exit 0` · Test Files **440 passed | 3 skipped (443)** · Tests **3645 passed | 41 skipped (3686)** · no failures. Also green on `57fd18f8` (440 | 3 files, 3642 | 41 tests). Ran because the title carries `!` and the claim's line carries the `(narrowing)` arm; not re-run for `30b6c84f`, which changes no file the battery reads. ## Kept - Same-package re-registration, the environment catalog (ADR-0005 overlay), every agent / skill / data / request / flow pin green unchanged; `rag_pipeline` keeps §3.4 as P1.9 left it; the cold boot stays `BARE_NAME_COLD_BOOT_MODE = 'warn'`. ## Acceptance notes - Cloud's `ToolRegistry.register` is a `Map.set`: a second code-registered tool under one name silently replaces the first (cloud reading 6725094995). That is cloud code, outside this card; carrier: cloud (the cloud seat files it, per seat 1). - Cloud mirrors code-registered tools into `tool` metadata only when absent (`register('tool', …, { notify: false })`, per the cloud reading). If that mirror ever registered package-bound after the cold-boot seal, a second plugin's same-named mirror would now be refused; the "when absent" guard means it never registers a name twice. NOT MEASURED against a running cloud build. - The addendum's own status line still reads "one family per change (P1.2, P1.7, P1.8, P1.9 — the last)": P1.10 is a dated note after the series, not a fifth family, and the ruling named four spots, so it is left as written. --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmS1DVx9CH1xvXikQBW)_ <!-- signed: domain:server#1 · os-steve · session_01ADHkmPF1skfu2kx89BEXZi --> --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 9e1f1f9 commit 1f30be1

8 files changed

Lines changed: 162 additions & 59 deletions

‎.changeset/31414-bare-name-tool.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
'@objectstack/objectql': minor
3+
---
4+
5+
feat(objectql)!: a tool holds one name per package — once the cold boot has sealed the registry, a package declaring a tool under a name another installed package holds is refused at install and registration, naming both holders and the rename; a boot that already holds such a clash warns.
6+
7+
Clause-②: no (narrowing) — the engine's package door (`SchemaRegistry.installPackage`) and item seam (`SchemaRegistry.registerItem`) refuse, after the cold boot, a package registration they accepted before: one whose tool bears a name another installed package holds. Nothing is widened.
8+
Metadata-protocol: narrowed
9+
Skills-docs: none — `skills/**` does not teach that two packages may share a tool name, and the naming rule itself is phase 2's (#30805); the prescription ships in the refusal and warning text and in ADR-0048's 2026-11-06 addendum (P1.10).
10+
11+
<!-- adr-0087: not-required (no-migration-prescription) the refusal removes no key, export or field and changes the shape of no stored body; what an author does about a refused name is pick a different one, which no conversion can choose for them -->
12+
13+
**BREAKING** accept-set narrowing at the package registration door, for tools: managed install (`install-local`, a post-start `manifest.register`, a hot reload) and package registration (`ObjectQL.registerApp` and every package-bound `registerItem`). `tool` joins the bare-name one-holder list after the AI family of maintainer ruling C on #30798, phase 1 (#30803), by the maintainer's acceptance of a separate card for it. ADR-0048 §3.4 narrowed (addendum 2026-11-06, P1.10).
14+
15+
- **Why.** Every reader of a tool names it with no package. Measured on a booted showcase with two packages sharing one tool name, in both registration orders: `/meta/tool/NAME` served the first-registered package's tool, silently, and a third package installed after the boot under that name installed (`200`) and was shadowed. The protocol a tool is called through carries a bare name and nothing else: a skill's `tools` list admits only a bare snake_case name, an AI tool definition and a tool call carry a name and no package, and an MCP server registers one tool per name (a second registration of a name throws).
16+
- **Before.** Two installed packages could each ship a tool under one name, at boot or by a later install; every caller was served one of them, chosen by registration order.
17+
- **Now.** After the cold boot (the engine plugin seals the registry at `kernel:bootstrapped`), a package registration declaring a tool under a name another installed package holds is refused ahead of every mutation, so it leaves no record behind. The envelope is the first family's: `code: 'NAMESPACE_CONFLICT'`, `status: 422`, `install-local` answering `422 PLUGIN_REGISTER_FAILED`, every conflicting name in one refusal, both holders named, the rename (the incoming package's namespace prefixed) carried, `conflicts[]` structured.
18+
- **The cold boot.** A deployment whose installed packages already share a tool name still boots: the one warning line names every such name, both holders and the rename, and changes nothing about which holder each caller is served (`BARE_NAME_COLD_BOOT_MODE` stays `'warn'`).
19+
- **Who moves.** An author whose package declares a tool under a name another package installed beside it already ships, at the next install or upgrade into a running deployment. **The one-line fix: rename the tool in one of the two packages — the refusal names the namespace-prefixed name — or uninstall one of them.** A skill, an agent's guardrail or an MCP client that named the old name must name the new one; nothing rewrites stored references.
20+
- **Unchanged.** The same package registering its own tool name again. An environment tool under a package's name (never judged, never a holder: the ADR-0005 overlay). One package's tool and another package's skill or agent under one name (different types). A `rag_pipeline`, and every other type the rule does not list (ADR-0048 §3.4 as written). `OS_METADATA_COLLISION=warn` does not downgrade the refusal.
21+
22+
**Measured producers.** On objectstack `69244406`, no example app and no platform package declares a tool (`app-showcase`'s coverage file defers tools, ADR-0063), so no shipped name has two holders. HotCRM is not checked out in this container and is NOT MEASURED here. Deployed and marketplace packages NOT MEASURED.

‎docs/adr/0048-cross-package-metadata-collision.md‎

Lines changed: 51 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
**Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md) (package as first-class citizen), [ADR-0005](./0005-metadata-customization-overlay.md) (artifact vs runtime overlay precedence), [ADR-0008](./0008-metadata-repository-and-change-log.md) (metadata repository, `MetaRef` identity), [ADR-0010](./0010-metadata-protection-model.md) (package provenance / `_packageId` stamping)
66
**Consumers**: `@objectstack/objectql` (`SchemaRegistry.registerItem`, `ObjectQL.registerApp`, install path), `@objectstack/console` / `objectui` (routing + metadata resolution), package authors, CLI/CI install path, the app marketplace registry.
77
**Surfaced by**: ADR-0046 review (doc naming) → generalised to all bare-named metadata → re-examined through the app-marketplace install lens.
8-
**Addenda**: [2026-08-08 — publish-time / marketplace namespace exclusivity](#addendum-2026-08-08-publish-time--marketplace-namespace-exclusivity) (**Accepted** 2026-08-08 — maintainer ruling on #1825, [acceptance comment 5226411687](https://github.com/objectstack-ai/objectstack/issues/1825#issuecomment-5226411687), landed by PR #6671; additive to §3.2, supersedes nothing); [2026-11-06 — bare names resolved without a package hold one package](#addendum-2026-11-06-bare-names-resolved-without-a-package-hold-one-package--34-narrowed) (**Accepted**, ruling C on #30798, phase 1; narrows §3.4 for picklists, mappings, datasets, APIs, object-less actions, engine functions, flows, webhooks, connectors, email templates, agents and skills — phase 1 complete — supersedes nothing).
8+
**Addenda**: [2026-08-08 — publish-time / marketplace namespace exclusivity](#addendum-2026-08-08-publish-time--marketplace-namespace-exclusivity) (**Accepted** 2026-08-08 — maintainer ruling on #1825, [acceptance comment 5226411687](https://github.com/objectstack-ai/objectstack/issues/1825#issuecomment-5226411687), landed by PR #6671; additive to §3.2, supersedes nothing); [2026-11-06 — bare names resolved without a package hold one package](#addendum-2026-11-06-bare-names-resolved-without-a-package-hold-one-package--34-narrowed) (**Accepted**, ruling C on #30798, phase 1; narrows §3.4 for picklists, mappings, datasets, APIs, object-less actions, engine functions, flows, webhooks, connectors, email templates, agents and skills — phase 1 complete — and, by its dated note P1.10 (2026-11-08), tools; supersedes nothing).
99

1010
---
1111

@@ -268,26 +268,26 @@ package — stays covered by the `naming/namespace-prefix` lint in `os lint`.
268268
269269
> **Narrowed (2026-11-06) — picklists, mappings, datasets, APIs, object-less
270270
> actions, engine functions, flows, webhooks, connectors, email templates, agents
271-
> and skills are out of §3.4.** Their consumers resolve the name with no package — a field's
271+
> and skills are out of §3.4, and tools since 2026-11-08 (P1.10).** Their consumers resolve the name with no package — a field's
272272
> `picklist`, an import's `mappingName`, a dashboard's `datasetName`, the
273273
> endpoint matcher's one API per name, `/actions/global/NAME`, a flow `script`
274274
> node's function, the automation engine's one armed flow per name, the
275275
> dispatcher's one declared webhook per name, the connector picker's one
276276
> connector per name, a send's `template`, `/meta/agent/NAME`, an MCP client's
277-
> skill prompt — so with two holders every caller is
277+
> skill prompt, `/meta/tool/NAME` and a skill's `tools` — so with two holders every caller is
278278
> served one of them, chosen by registration order, measured on a booted
279279
> two-package deployment (#30803). Once the cold boot has sealed the registry, a
280280
> package whose picklist, mapping, dataset, API, object-less action, flow,
281-
> webhook, connector, email template, agent or skill bears a name another
281+
> webhook, connector, email template, agent, skill or tool bears a name another
282282
> installed package holds is refused at managed install and at package registration (a built-in's
283283
> name, at managed install), and a package whose handlers bring a function
284284
> another package holds is refused at the hook binder's bind, each naming both
285285
> holders and the rename. ⛔ The environment catalog is never a holder: an
286286
> environment item under a package's name is the ADR-0005 overlay. ⛔ Nor is the
287287
> email service's built-in template bundle: an app's same-named template
288288
> overrides it by contract (ADR-0131 D6), so that package holds no template name
289-
> and is refused none. Every other type keeps §3.4 as written, among them a
290-
> `tool` and an action bound to an object. See
289+
> and is refused none. Every other type keeps §3.4 as written, among them an
290+
> action bound to an object. See
291291
> [Addendum (2026-11-06)](#addendum-2026-11-06-bare-names-resolved-without-a-package-hold-one-package--34-narrowed).
292292
293293
### 3.5 Namespace rename-on-install is deferred (non-goal)
@@ -1069,7 +1069,8 @@ first, as the maintainer ordered on 2026-11-06 (all of them kept in #30803): the
10691069
data family (P1.1), the request family (P1.7), the flow family (P1.8) and, last,
10701070
the AI family — `agent` and `skill` (P1.9). P1.9's change closes phase 1. `tool`
10711071
and `rag_pipeline` were never in the ruling's list; P1.9 records what was
1072-
measured of them.
1072+
measured of them. `tool` joined afterwards, on its own card and measurement
1073+
(P1.10, 2026-11-08); `rag_pipeline` stays out.
10731074

10741075
### P1.6 Where it is implemented
10751076

@@ -1203,13 +1204,51 @@ holders, the same envelope and rename. Neither is bundled, and neither has an
12031204
overridable baseline or a built-in name. An agent and a skill are two types: one
12041205
package's agent and another's skill under one name never meet.
12051206

1206-
**Not in the list.** A `tool` is not covered — the ruling's types do not name it.
1207-
Measured beside them: `/meta/tool/NAME` serves the first-registered package's
1208-
tool as well; the readers that resolve a tool by name are the cloud's. A
1207+
**Not in the list.** A `tool` is not covered by this change — the ruling's types
1208+
do not name it. Measured beside them: `/meta/tool/NAME` serves the
1209+
first-registered package's tool as well. (It joined the list later, on its own
1210+
card and measurement: P1.10.) A
12091211
`rag_pipeline` cannot be declared through `defineStack` (the stack schema
1210-
refuses `ragPipelines`) and registered nothing in the measurement. Both are left
1211-
as §3.4 has them.
1212+
refuses `ragPipelines`) and registered nothing in the measurement. `rag_pipeline` is left
1213+
as §3.4 has it.
12121214

12131215
**The cold boot** reads the two with the registry's other holders, under P1.3's
12141216
switch (`'warn'`). This is the series' closing change: phase 1's list is
12151217
complete, and phase 2 (#30804, #30805) and phase 3 (#30806) follow.
1218+
1219+
### P1.10 (2026-11-08) `tool` joins the list, after the AI family
1220+
1221+
A dated note under this addendum; it narrows §3.4 for one more type. The
1222+
header's Addenda entry, §3.4's 2026-11-06 note, P1.5 and P1.9's "Not in the
1223+
list" name it beside the earlier types. The maintainer accepted a separate card for `tool` out of P1.9's
1224+
measurement (「以上都同意」, 2026-11-08, #31414): measure the readers that resolve a
1225+
tool by name, and if any carries no package, `tool` joins P1.2's list the way
1226+
the AI family did.
1227+
1228+
**Measured** on objectstack `69244406`, beside P1.9's booted measurement:
1229+
1230+
- `/meta/tool/NAME` serves the FIRST-registered package's tool, silently, in
1231+
either registration order (P1.9), and a third package installed after the boot
1232+
under that name installs (`200`) and is shadowed.
1233+
- Every reference to a tool carries its bare name and nothing else. A skill's
1234+
`tools` list admits only a snake_case name (the spec's `SkillSchema`, bound by
1235+
the cloud agent runtime); an AI tool definition and a tool call carry a name
1236+
and no package (`AIToolDefinition`, `ToolCallPart` in the AI service
1237+
contract); the MCP bridge registers each tool under its name and calls it by
1238+
that name, and an MCP server holds one tool per name (a second registration of
1239+
a name throws). An agent's guardrail matches a tool by its name.
1240+
- The cloud agent runtime (read by the cloud seat at objectstack-ai/cloud
1241+
`ba6f0fa`, #31414) resolves a tool by bare name too, for chat (a skill's
1242+
`tools`) and MCP alike, against an in-process tool registry keyed by the name
1243+
that plugins fill in code; the metadata `tool` item is a mirror for Studio and
1244+
reaches no handler there. So no reader on either side carries a package, and
1245+
one such reader is enough.
1246+
1247+
**What is refused.** `tool` joins P1.2's list, last: the same two doors, the
1248+
same holders, the same envelope and rename. It is not bundled, and it has no
1249+
overridable baseline and no built-in name. An agent, a skill and a tool are
1250+
three types: one package's item of one and another package's item of another
1251+
under one name never meet.
1252+
1253+
**The cold boot** reads it with the registry's other holders, under P1.3's
1254+
switch (`'warn'`). `rag_pipeline` stays as P1.9 left it.

‎packages/objectql/src/bare-name-one-holder.ts‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@
1111
* under #30803: the data family first, then the request family (`api`, the
1212
* object-less `action`, the engine's function registry), then the flow family
1313
* (`flow`, `webhook`, `connector`, `email_template`), and last the AI family
14-
* (`agent`, `skill`), which closes the series.
14+
* (`agent`, `skill`), which closed the series. `tool` joined after it, in its
15+
* own change under #31414, once its readers were measured.
1516
*
1617
* ## The rule
1718
*
@@ -60,7 +61,12 @@
6061
* - `skill` — an MCP client's `prompts/get` of a skill keeps the
6162
* FIRST-registered package's skill (`listSkillPrompts` keeps the first
6263
* row per name and drops the other), and `/meta/skill/NAME` serves the
63-
* same one.
64+
* same one;
65+
* - `tool` — `/meta/tool/NAME` serves the FIRST-registered package's tool,
66+
* and every reference to a tool carries its bare name alone: a skill's
67+
* `tools` list admits only a snake_case name, an AI tool definition and a
68+
* tool call carry a name and no package, and an MCP server registers one
69+
* tool per name.
6470
*
6571
* Every one of them flips with registration order, and none says so (the
6672
* object-less action's handler bind warns that it replaces one, and names
@@ -154,7 +160,7 @@ export type BareNameRegistryType =
154160
| 'picklist' | 'mapping' | 'dataset'
155161
| 'api' | 'action'
156162
| 'flow' | 'webhook' | 'connector' | 'email_template'
157-
| 'agent' | 'skill';
163+
| 'agent' | 'skill' | 'tool';
158164

159165
/**
160166
* A covered type: a registry type, or `function` — the engine's function
@@ -183,6 +189,8 @@ export const BARE_NAME_ONE_HOLDER_TYPES: readonly BareNameOneHolderType[] = Obje
183189
// the AI family
184190
'agent',
185191
'skill',
192+
// joined after the AI family, in its own change
193+
'tool',
186194
]);
187195

188196
/** The covered registry types, in the order a refusal lists them. */
@@ -227,6 +235,7 @@ const COLLECTION_KEY: Readonly<Record<BareNameRegistryType, string>> = Object.fr
227235
email_template: 'emailTemplates',
228236
agent: 'agents',
229237
skill: 'skills',
238+
tool: 'tools',
230239
});
231240

232241
/**
@@ -248,6 +257,7 @@ export const BUILT_IN_BARE_NAMES: Readonly<Record<BareNameOneHolderType, Readonl
248257
email_template: new Set<string>(),
249258
agent: new Set<string>(),
250259
skill: new Set<string>(),
260+
tool: new Set<string>(),
251261
});
252262

253263
/**
@@ -277,6 +287,7 @@ export const OVERRIDABLE_BASELINE_PACKAGES: Readonly<Record<BareNameOneHolderTyp
277287
email_template: new Set<string>(['com.objectstack.service.email']),
278288
agent: new Set<string>(),
279289
skill: new Set<string>(),
290+
tool: new Set<string>(),
280291
});
281292

282293
/**
@@ -403,6 +414,7 @@ const CONSUMER_CLAUSE: Readonly<Record<BareNameOneHolderType, string>> = Object.
403414
email_template: 'a send names its email template',
404415
agent: '`/meta/agent/NAME` serves one agent per name',
405416
skill: 'an MCP client fetches a skill\'s prompt by its name',
417+
tool: 'a skill\'s `tools` and an MCP client name a tool',
406418
});
407419

408420
/** The noun a reason names a covered type by. */
@@ -419,6 +431,7 @@ const TYPE_NOUN: Readonly<Record<BareNameOneHolderType, string>> = Object.freeze
419431
email_template: 'an email template',
420432
agent: 'an agent',
421433
skill: 'a skill',
434+
tool: 'a tool',
422435
});
423436

424437
const joinList = (parts: readonly string[]): string =>

‎packages/objectql/src/plugin.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ import {
7272
import { SecurityCatalogNameConflictError, findEnvironmentHeldSecurityCatalogNames } from './registry.js';
7373
// One name, one package holder for the bare-name types (a picklist, a mapping, a
7474
// dataset, an API, an object-less action, a function, a flow, a webhook, a
75-
// connector, an email template, an agent, a skill) — the cold boot's seal and its one switch
75+
// connector, an email template, an agent, a skill, a tool) — the cold boot's seal and its one switch
7676
// (`bare-name-one-holder.ts`, "The cold boot").
7777
import { sealBareNameHoldersAtColdBoot } from './registry.js';
7878
import { BARE_NAME_COLD_BOOT_MODE } from './bare-name-one-holder.js';

0 commit comments

Comments
 (0)