proto: drop redundant agent segment from package namespace - #7
Merged
Conversation
Package namespace was pluggableharness.agent.<category>.v1; the agent segment added a repo-name echo with no disambiguating value since pluggableharness is already the org anchor and <category>.v1 already names the protocol and version. Now pluggableharness.<category>.v1. Moves api/pluggableharness/agent/<category>/ to api/pluggableharness/<category>/ (buf's PACKAGE_DIRECTORY_MATCH), updates every package/import declaration and fully-qualified type reference across all 18 category protos, and regenerates pkg/*/proto/v1. go_package stays github.com/pluggableharness/agent/pkg/<category>/proto/v1 unchanged — that's the real Go module path, not the proto namespace, so no generated file moves and no Go import path anywhere changes. Safe now because no v* release tag exists yet: buf breaking is scoped to the first released tag onward (.claude/rules/proto.md), and ci.yml's breaking-change check no-ops with no tag present. Once a tag lands this would have to ship as a new v2 package instead.
Mirrors the proto namespace rename: attribute.Key and metric instrument names in internal/telemetry were deliberately namespaced pluggableharness.agent.* to match the (now former) proto package prefix. Kept in sync rather than letting the two conventions drift. Also updates the KernelCallbackService gRPC service-name assertion in internal/pluginruntime/adapter_test.go (proto-derived, changes because the proto package changed) and doc comments in internal/log, internal/producer, and pkg/common that named the old proto package. internal/telemetry/span_test.go is untouched on purpose: its .pluggableharness.agent.lock.hcl string is an on-disk lock-file name, a distinct use of the string from both the proto namespace and the OTel attribute prefix. Nothing here changes the go-plugin handshake magic cookie (pkg/common/plugin.go) or the pluggableharness-agent OTel service_name default (internal/config, internal/telemetry/config.go) — both are product/handshake identifiers, not namespace conventions.
Follows the proto/telemetry rename in the two prior commits. Updates .claude/rules/proto.md and go-layout.md (the convention definitions), .github/instructions/proto.instructions.md (the Copilot-facing restatement), and every docs/specifications/ and internal/ package doc that names a fully-qualified proto package or type.
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
There was a problem hiding this comment.
Pull request overview
Renames the protobuf namespace by dropping the redundant agent segment (pluggableharness.agent.<category>.v1 → pluggableharness.<category>.v1) across source protos, regenerated Go stubs, telemetry naming, and the specification/docs set so the wire contract is consistently shorter before the first v* release tag.
Changes:
- Updated all
.protopackagedeclarations and intra-proto type references/imports to the newpluggableharness.<category>.v1namespace (withgo_packageunchanged). - Regenerated
pkg/*/proto/v1/*.pb.goand*_grpc.pb.gooutputs to reflect new service/method/type full names. - Updated kernel telemetry metric names and OTel attribute keys, and updated specs/docs/instructions to match the new fully-qualified names.
Reviewed changes
Copilot reviewed 73 out of 75 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| pkg/widget/proto/v1/widget_grpc.pb.go | Regenerated gRPC service/method name constants to pluggableharness.widget.v1. |
| pkg/tool/proto/v1/tool_grpc.pb.go | Regenerated gRPC service/method name constants to pluggableharness.tool.v1. |
| pkg/slashcommand/proto/v1/slashcommand.pb.go | Regenerated descriptor/type references to pluggableharness.slashcommand.v1. |
| pkg/session/proto/v1/session.pb.go | Regenerated descriptor/type references to pluggableharness.session.v1. |
| pkg/schema/proto/v1/schema.pb.go | Regenerated descriptor/type references to pluggableharness.schema.v1. |
| pkg/plan/proto/v1/plan.pb.go | Regenerated plan types and cross-package enum/type references to new namespaces. |
| pkg/model/proto/v1/model_grpc.pb.go | Regenerated gRPC service/method name constants to pluggableharness.model.v1. |
| pkg/memory/proto/v1/memory_grpc.pb.go | Regenerated gRPC service/method name constants to pluggableharness.memory.v1. |
| pkg/log/proto/v1/log.pb.go | Regenerated log types to pluggableharness.log.v1 namespace references. |
| pkg/kernel/proto/v1/kernel_grpc.pb.go | Regenerated KernelCallbackService names to pluggableharness.kernel.v1. |
| pkg/hook/proto/v1/hook_grpc.pb.go | Regenerated hook subscriber gRPC surface names to pluggableharness.hook.v1. |
| pkg/frontend/proto/v1/frontend_grpc.pb.go | Regenerated frontend gRPC surface names to pluggableharness.frontend.v1. |
| pkg/event/proto/v1/event.pb.go | Regenerated event payload type graph to pluggableharness.event.v1 and updated imported type names. |
| pkg/context/proto/v1/context_grpc.pb.go | Regenerated context gRPC surface names to pluggableharness.context.v1. |
| pkg/config/proto/v1/config.pb.go | Regenerated config schema types to pluggableharness.config.v1. |
| pkg/common/proto/v1/common.pb.go | Regenerated shared common types to pluggableharness.common.v1. |
| pkg/common/plugin.go | Updated package comment references to the new common proto namespace. |
| internal/telemetry/usage_test.go | Updated metric-name assertions to the new pluggableharness.* names. |
| internal/telemetry/instrument.go | Renamed metric instruments from pluggableharness.agent.* to pluggableharness.*. |
| internal/telemetry/instrument_test.go | Updated failing-meter test case to target the new metric name. |
| internal/telemetry/grpchooks_test.go | Updated OTEL_RESOURCE_ATTRIBUTES formatting expectations for renamed attribute keys. |
| internal/telemetry/attributes.go | Renamed OTel attribute keys from pluggableharness.agent.* to pluggableharness.* (and removed redundant agent.agent). |
| internal/telemetry/attributes_test.go | Updated attribute-key string assertions to match renamed keys. |
| internal/producer/README.md | Updated doc references to pluggableharness.common.v1.ProducerRef. |
| internal/producer/doc.go | Updated package doc references to pluggableharness.common.v1.ProducerRef. |
| internal/pluginruntime/adapter_test.go | Updated callback service registration assertion to pluggableharness.kernel.v1.KernelCallbackService. |
| internal/log/level.go | Updated comment references to pluggableharness.log.v1.LogLevel. |
| internal/log/handler.go | Updated comment references to pluggableharness.kernel.v1 KernelCallbackService. |
| internal/log/doc.go | Updated package doc references to new log.v1 / kernel.v1 namespaces. |
| internal/eventbus/eventbus_test.go | Updated metric-name assertion to pluggableharness.eventbus.events.published. |
| docs/specifications/tool/README.md | Updated prose references to pluggableharness.schema.v1.Schema. |
| docs/specifications/tool/protocol.md | Updated type references (HookPoint, RenderTree, ProducerRef, PlanItem.preview) to new namespaces. |
| docs/specifications/tool/examples.md | Updated protobuf examples to new fully-qualified type names. |
| docs/specifications/tool/data-types.md | Updated inline type reference for CallContext to new namespace. |
| docs/specifications/state-backend.md | Updated event/hook payload package references to pluggableharness.event.v1 and pluggableharness.hook.v1. |
| docs/specifications/memory/protocol.md | Updated hook service namespace reference to pluggableharness.hook.v1. |
| docs/specifications/kernel-callbacks.md | Updated event package reference to pluggableharness.event.v1. |
| docs/specifications/frontend/widget-protocol.md | Updated widget protocol examples to new render/config/common namespaces. |
| docs/specifications/frontend/frontend-protocol.md | Updated protocol examples to new content/render/plan/session namespaces. |
| docs/specifications/context/examples.md | Updated context example type references to new model/content namespaces. |
| docs/specifications/context/data-types.md | Updated canonical ContextSection location reference to pluggableharness.content.v1. |
| docs/specifications/architecture.md | Updated hook subscriber wire surface reference to pluggableharness.hook.v1. |
| docs/specifications/agent-loop/README.md | Updated hook-dispatch wire contract namespace reference. |
| docs/specifications/agent-loop/hook-dispatch.md | Updated hook-dispatch wire contract/service/package path references to new namespace. |
| api/pluggableharness/widget/v1/widget.proto | Updated package and imported type references to new namespaces. |
| api/pluggableharness/tool/v1/tool.proto | Updated package, imports, and type references (schema/render/common/slashcommand) to new namespaces. |
| api/pluggableharness/slashcommand/v1/slashcommand.proto | Updated package to pluggableharness.slashcommand.v1. |
| api/pluggableharness/session/v1/session.proto | Updated package to pluggableharness.session.v1. |
| api/pluggableharness/schema/v1/schema.proto | Updated package to pluggableharness.schema.v1. |
| api/pluggableharness/render/v1/render.proto | Updated package to pluggableharness.render.v1. |
| api/pluggableharness/plan/v1/plan.proto | Updated package, imports, and type references (render/tool/content/schema) to new namespaces. |
| api/pluggableharness/model/v1/model.proto | Updated package, imports, and type references (content/render/schema/common/config/slashcommand) to new namespaces. |
| api/pluggableharness/memory/v1/memory.proto | Updated package, imports, and type references (common/config/content/model/render/slashcommand) to new namespaces. |
| api/pluggableharness/log/v1/log.proto | Updated package and kernel service reference comment to new namespace. |
| api/pluggableharness/kernel/v1/kernel.proto | Updated package, imports, and type references (common/content/log/model/session) to new namespaces. |
| api/pluggableharness/hook/v1/hook.proto | Updated package, imports, and all payload type references to new namespaces. |
| api/pluggableharness/frontend/v1/frontend.proto | Updated package, imports, and all message references (common/config/content/model/plan/render/session/slashcommand) to new namespaces. |
| api/pluggableharness/event/v1/event.proto | Updated package, imports, and event payload message references to new namespaces. |
| api/pluggableharness/context/v1/context.proto | Updated package, imports, and type references (common/config/content/model/render/slashcommand) to new namespaces. |
| api/pluggableharness/content/v1/content.proto | Updated package to pluggableharness.content.v1 and adjusted cross-doc references. |
| api/pluggableharness/config/v1/config.proto | Updated package to pluggableharness.config.v1. |
| api/pluggableharness/common/v1/common.proto | Updated package to pluggableharness.common.v1. |
| .github/instructions/proto.instructions.md | Updated repo instructions to reflect the new package namespace convention. |
| .claude/rules/proto.md | Updated proto packaging rules/examples to the new namespace and directory layout. |
| .claude/rules/go-layout.md | Updated layout docs for api/pluggableharness/<category>/v1/*.proto path pattern. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Drops the redundant
agentsegment from the proto namespace:pluggableharness.agent.<category>.v1becomespluggableharness.<category>.v1.pluggableharnessalready anchors the org and<category>.v1already names the protocol and version, soagentadded a repo-name echo with no disambiguating value — every fully-qualified message name was one segment longer than it needed to be.This has to land before the first
v*release tag:.claude/rules/proto.mdmakes a releasedv1contract permanent, andbuf breakingonly starts enforcing that from the first tag onward (it no-ops today, perci.yml). After a tag, this same rename would have to ship as av2package next tov1, forever.Three commits:
proto: ...— moves all 18api/pluggableharness/agent/<category>/dirs up toapi/pluggableharness/<category>/(buf'sPACKAGE_DIRECTORY_MATCH), updates everypackage/importdeclaration and fully-qualified type reference, regeneratespkg/*/proto/v1.go_package(and therefore every Go import path) is unchanged — that's the real module path (github.com/pluggableharness/agent), not the proto namespace, so this is proto/wire-only.telemetry: ...—internal/telemetry's OTel attribute keys and metric names deliberately mirrored the samepluggableharness.agent.*prefix; renamed in lockstep so the two conventions don't drift apart. Also updates theKernelCallbackServicegRPC service-name assertion ininternal/pluginruntime/adapter_test.go(proto-derived).docs: ...— updates the convention definitions (.claude/rules/proto.md,go-layout.md), the Copilot-facing restatement (.github/instructions/proto.instructions.md), and everydocs/specifications// package doc naming a fully-qualified proto type.Explicitly not touched (share the substring, different identity): the Go module path
github.com/pluggableharness/agent; the go-plugin handshake magic cookie inpkg/common/plugin.go;pkg/common.ProtocolVersion(no proto version bump, since nothing shipped); thepluggableharness-agentOTelservice_name/product identifier; andinternal/telemetry/span_test.go's.pluggableharness.agent.lock.hcllock-file name, a third, unrelated use of the dotted string.Checklist
go mod tidyis a no-op,go build ./...,go vet ./...,gofmt -l -s .prints nothing,go test -race -covermode=atomic ./...,golangci-lint rundocs/specifications/document in this same PRpkg/*/proto/v1/—.protochanges made inapi/and regenerated withbuf generateinternal/packages includeREADME.md+CLAUDE.mdin the same commit — n/a, no new packagesbin/Notes for reviewers
Verified beyond the checklist:
buf lint,buf format --diff --exit-code, and re-runningbuf generateafter the final commit leavesgit status --porcelain -- pkgempty (no drift). Also grepped the whole tree for both the dotted (pluggableharness.agent.) and slash (pluggableharness/agent/) forms post-change — the only two remaining hits are the intentionally-protected lock-file-name lines inspan_test.go, and confirmed thegithub.com/pluggableharness/agentmodule-path string count is unchanged (9 removed / 9 re-added across regenerated.pb.gofiles, same total elsewhere).