[Epic] Manager-scoped agent discovery via org hierarchy resolver

[vivekkrishna]

Problem Statement

The Agent Directory Service supports annotation-based search (e.g., `owner.id: alice@example.com`), but there is no way to ask: "give me all agents owned by anyone in Alice's org subtree."

Today a user must:

1. Manually query their HR/directory system to enumerate every IC under a given manager
2. Issue one search per owner alias, or construct the full owner list themselves

This is impractical at scale — a manager may have hundreds of direct and indirect reports — and it puts the burden of org resolution on the caller.

Proposed Solution

Introduce a pluggable OrgResolver interface in the ADS server that can expand a manager alias into a full list of aliases in their reporting chain. This enables a single query:

```
dirctl search --manager alice@example.com
```

Which internally:

1. Calls the configured OrgResolver with `alice@example.com`
2. Receives the full subtree: `[alice, bob, carol, dave, ...]`
3. Fans out to annotation search: `owner.id IN [alice, bob, carol, dave, ...]`
4. Returns all matching agent records

OrgResolver interface (sketch):
```go
type OrgResolver interface {
// Expand returns the manager and all direct/indirect reports under them.
Expand(ctx context.Context, managerAlias string) ([]string, error)
}
```

Resolver implementations (pluggable, configured in server config):

• static — file-based mapping (YAML/JSON), useful for testing and air-gapped environments
• http — generic REST adapter with configurable endpoint and response mapping, covers Workday, BambooHR, and other HR APIs without hard-coding vendor logic

The resolver is optional — when unconfigured, --manager returns an error and all other search behavior is unaffected.

Annotation convention (recommended, not enforced):
```
annotations:
owner.id: "alice@example.com"
owner.type: "user"
```

Alternatives Considered

Client-side resolution: The CLI could call the HR system directly and pass the expanded owner list to annotation search. Simpler to implement, but leaks org structure to every client, requires every CLI user to have credentials for the HR system, and duplicates resolver logic across clients.

Per-vendor integrations (Workday, BambooHR, LDAP): Tight integrations with specific HR APIs would provide richer data but introduce vendor coupling and maintenance burden. A generic HTTP adapter with configurable field mapping covers the same cases without lock-in.

New first-class schema field: Adding a dedicated owner schema block (Phase 2 of #1445) would be more structured, but adds schema complexity and migration burden. The annotation-based approach delivers immediate value with zero schema changes.

Additional Context

• Builds directly on annotation-based search introduced in feat(dir): add annotation-based search support #1442
• Represents Phase 3 of the ownership epic [Epic] Agent Ownership & Org-Aware Governance #1445
• The resolver is intentionally optional and pluggable — no mandatory dependency on any HR system
• Initial scope: static and http resolver implementations; LDAP/IdP resolvers can follow in later PRs

[vivekkrishna]

Capturing @ramizpolic input in PR for design discussion:

Hi @vivekkrishna, thank you for contributing. I do agree that ownership is something that needs to be addressed, but I am not sure if this is the approach we would want to take. There are two important things that I would like to adjust here:

Rather than doing ownership claims through annotations, we can patch OASF with dedicated fields to make it more explicit
Local discovery vs network discovery is not addressed here and only impacts local discovery
For this PR to go forward, I would suggest we start from an issue/discussion and agree on a plan collectively as this is an important feature. We do support right now ownership through DNS/HTTPs claims through record naming (e.g. my-agent vs https://microsoft.com/agents/my-agent/v1.0.0 but we have no way to aggregate these locally or on the network.

[vivekkrishna]

Revised Design Proposal — manager-scoped discovery with first-class ownership

Following @ramizpolic's feedback on #1469, here is a revised approach that addresses both concerns: ownership as a first-class schema field (not annotation-based), and a path toward both local and network discovery.

---

1. owners field in OASF record schema

We propose adding an owners field to the OASF record object (agntcy/oasf). This is distinct from the existing authors field — authors captures attribution/provenance, owners captures operational responsibility and is the field the directory uses for discovery.

owners:
  - type: user | team | organization | service
    alias: alice               # handle used for org chart resolution
    org: acme.com              # namespace that scopes the alias; links to org chart
    email: alice@acme.com      # optional, contact/notification address
    display_name: Alice        # optional, human-readable label
    verification:
      method: dns | https | oidc | signed_claim   # open question, see below

Key design decisions:

• alias is the resolution token — what the OrgResolver expands. It can be a short username, a team slug, or an email. Keeping it separate from email avoids conflating identity (used for resolution) with contact address.
• org is the namespace that scopes the alias. alice at acme.com and alice at other-corp.com are distinct identities. org also implicitly selects which org chart resolver to use (see §2).
• (alias, org) is the composite identity. Neither field is meaningful alone.
• type: service is included alongside user | team | organization to cover CI pipelines, bots, and automated deployers as valid owner entities.
• verification is called out as an open question — it aligns with the existing DNS/HTTPS ownership claim mechanism in the dir server, but needs its own design pass.

Open questions:

• Should owners be optional or recommended in the schema?
• Should authors be enriched with a role attribute instead of introducing a new owners field? Our preference is a separate field (cleaner semantics, no migration burden on existing records), but worth a team call.
• verification.method — who verifies, when, and signed by what? Leaving this as a placeholder for now.
• Should org be constrained (e.g. must be a domain or URI) or a free-form string?

---

2. org_resolvers in server config

The server config maps org values to resolver implementations. org in the record is the key; the resolver is the server-side mechanism for expanding a manager alias into their full subtree.

server:
  org_resolvers:
    acme.com:
      type: static
      file: org-chart-acme.yaml
    other-corp.com:
      type: http
      endpoint: https://api.other-corp.com/org

Resolver types (pluggable, configured per org):

• static — YAML/JSON file, useful for testing and air-gapped environments
• http — generic REST adapter covering Workday, BambooHR, and similar HR APIs without vendor lock-in; field mapping is configurable
• ldap, scim, oidc — can follow in later PRs once the interface is established

The resolver is optional per org — if org_resolvers is absent or a given org has no entry, --manager returns an informative error. All other search is unaffected.

---

3. Search strategy

Two new CLI flags, each single-purpose:

# Expand alice's full org subtree at acme.com and return all owned agents
dirctl search --manager alice --org acme.com

# Direct owner lookup without subtree expansion
dirctl search --owner platform-team --org acme.com

# Combined with existing filters
dirctl search --manager alice --org acme.com --skill summarization

--manager triggers subtree expansion via the org resolver. --owner is a direct match against owners[*].alias + owners[*].org with no expansion.

Splitting --manager and --org keeps each flag single-purpose and avoids fragile inference (e.g. parsing a domain out of an email alias). If --org is omitted and the alias is an email address, the server may optionally fall back to parsing the domain — but this is a convenience shortcut, not the primary resolution path.

Resolution flow for --manager alice --org acme.com:

1. Look up acme.com in org_resolvers → select the configured resolver
2. Call resolver.Expand("alice") → returns full subtree [alice, bob, carol, dave, ...]
3. Query: owners[*].org == "acme.com" AND owners[*].alias IN [alice, bob, carol, dave, ...]
4. Return matching records

---

4. Local discovery

In the local (database) layer:

• owners is stored as an indexed field on records
• A new RECORD_QUERY_TYPE_OWNER is added to the search proto for direct owner matching
• --manager expansion happens server-side: the controller calls the OrgResolver, then fans out into RECORD_QUERY_TYPE_OWNER queries scoped to (alias, org)
• A composite index on (owners.alias, owners.org) makes these queries efficient
• --manager and --owner can be combined with all existing filters (--skill, --annotation, etc.) without interference

---

5. Network discovery (potential path)

In the network (p2p routing) layer, discovery currently works via content-addressed announcements over libp2p/DHT. Extending this to support owner-scoped queries requires carrying ownership metadata in routing announcements:

• When a record is published to the network, owners[*].alias and owners[*].org are included in the routing announcement payload alongside the content identifier
• Remote peers index announced records by (alias, org) and can respond to owner-scoped queries
• For --manager queries: the querying node expands the org subtree locally (via its configured resolver), then issues parallel owner queries across the network for each alias in the subtree
• Alternatively, a batched owner query could be propagated to remote peers, which filter against their local index — reducing round trips at the cost of a routing proto change

This requires an extension to the routing proto and is proposed as a follow-on phase once the OASF field and local discovery land. Happy to scope that separately or include it here if the team prefers atomic delivery.

---

Proposed phasing

Phase	Scope	Repo
1	Add owners object + field to record schema	agntcy/oasf
2	Add RECORD_QUERY_TYPE_OWNER, index owners in DB, --owner flag	agntcy/dir
3	org_resolvers config, OrgResolver interface, --manager + --org flags	agntcy/dir
4	Extend routing announcements to carry owner fields; network-scoped owner search	agntcy/dir

Phases 1–3 are tightly coupled and could ship together. Phase 4 needs routing proto design and can follow as a tracked issue.

Happy to open a draft PR against agntcy/oasf for the schema change to make this concrete. Feedback welcome on any of the open questions above.

[vivekkrishna]

Scoping: intranet-first, network discovery as a future phase

After further discussion, we think the right primary target for this feature is private node deployments for agentic intranet use cases — a single org, local config, no DHT or federation complexity.

This is a well-defined, immediately valuable scope: an enterprise runs their own dir server, configures their org chart locally via org_resolvers, and gets --manager search across all agents owned by anyone in a manager's subtree. No cross-org trust, no DHT privacy concerns, no verification protocol needed to ship.

The revised phasing:

Phase	Scope
1	Add owners object + field to record schema (agntcy/oasf)
2	RECORD_QUERY_TYPE_OWNER, index owners in DB, --owner --org flags (agntcy/dir)
3	org_resolvers local config, OrgResolver interface, --manager --org flags (agntcy/dir)
4	Network/DHT discovery — explicitly deferred, tracked as a separate issue

Phase 4 is worth keeping on the radar. The org field and (alias, org) composite identity already lay the groundwork — org charts as optionally publishable DHT records (authenticated via DNS/HTTPS) is the natural extension when the team is ready to tackle federation. But the trust model, access control, and verification protocol that requires are a separate design conversation.

For now, Phases 1–3 are the target. Happy to open a draft PR against agntcy/oasf for the schema change as the first concrete step.

[vivekkrishna]

Two additional design points for discussion

---

A. Referrer-based ownership as an alternative (or complement)

The dir server already has a first-class referrer system at the OCI store layer (PushReferrer, WalkReferrers, DeleteReferrer) used today for signatures and public keys. This raises the question: should ownership claims be expressed as referrers attached to records rather than as an inline owners field?

The case for referrer-based ownership:

• Ownership claims can be attached or updated without modifying the record itself — changing the inline owners field changes the record's CID, which is a significant side effect for content-addressed storage
• Referrers can be signed using the existing SignatureReferrerType mechanism, which directly addresses the verification open question without a separate design pass
• Third-party ownership claims (e.g. an enterprise claiming ownership of a community-published agent) are a natural fit for referrers — they don't require the original author to modify the record

The problem:

• Referrers are not in the search index. A --manager query would have to walk referrers for every candidate record — expensive and unscalable for large registries.

A possible middle ground — two-layer ownership:

• owners stays inline in the record for indexability and fast --owner / --manager search
• A new OwnershipReferrerType is introduced for signed, externally-verifiable ownership proofs — the referrer carries the cryptographic claim, the inline field carries the searchable identity
• The two reference each other: the inline owners entry points to the referrer CID that backs it

This is worth considering especially if ownership verification becomes a requirement, since the referrer infrastructure for signing already exists.

---

B. Org chart pluggability — external to ADS vs pluggable inside ADS

Org charts come in many forms: flat YAML files, LDAP/Active Directory, SCIM (Okta, Azure AD, Google Workspace), HR REST APIs (Workday, BambooHR), Git-based teams (GitHub, GitLab), custom databases. The question is where the resolution interface should live.

Option 1 — fully external: the client resolves the org chart, expands the subtree, and passes the alias list to ADS as a plain --owner query. ADS has no knowledge of org charts.

• Pro: ADS stays simple, no coupling to org systems
• Con: every client needs org credentials; resolution logic duplicated across clients; network discovery is impossible (remote nodes cannot expand org charts on the caller's behalf)

Option 2 — pluggable inside ADS: ADS defines a narrow OrgResolver interface (Expand(alias, org) → []aliases) and ships implementations as plugins. The critical insight is that one plugin type is http — a generic REST adapter that calls any external service. This makes ADS pluggable without hardcoding vendor logic.

built-in:  static (YAML file), ldap, scim
external:  http → calls any org service the operator runs

This is the same pattern Kubernetes uses for storage (CSI), networking (CNI), and auth (webhook) — a pluggable interface with both native and external implementations, where the external escape hatch covers everything the built-ins don't.

Recommendation: Option 2, with http as the primary escape hatch for enterprise and SaaS org systems. The interface stays narrow and stable; implementations evolve independently. static and http ship first; ldap and scim can follow as the interface proves out.

The org field on the owners schema entry is the key that maps to the resolver — org: acme.com routes to the acme.com resolver configured in org_resolvers, regardless of whether that resolver is a local file or a remote Workday API.

Keen to hear the team's preference on both points before proceeding with the OASF schema PR.

[vivekkrishna]

https://agent-card.github.io/ai-catalog/#catalog-entry

[vivekkrishna]

Standards alignment — AI Catalog spec

Before we finalize the owners schema in OASF, it's worth looking at the AI Catalog specification, which is working on the same problem space: AI artifact discovery with publisher identity and trust.

What the AI Catalog spec defines

Each CatalogEntry has a publisher field and an optional TrustManifest:

Publisher = {
  identifier: text,       # who published this artifact
  displayName: text,
  ? identityType: text    # type of identity
}

TrustManifest = {
  identity: text,
  ? identityType: text,
  ? attestations: [* Attestation],
  ? provenance: [* ProvenanceLink],
  ? signature: text,
  ? metadata: { * text => any }
}

Where it aligns with our proposal

AI Catalog	Our proposal
publisher.identifier	owners[*].alias
publisher.identityType	owners[*].type: user | team | organization | service
TrustManifest.identity + signature	owners[*].verification.method (our open question)
host (catalog operator)	owners[*].org (namespace)

Notably, their TrustManifest already covers the verification open question we've been deferring — attestations, provenance links, and cryptographic signatures are all in scope there.

What's missing from AI Catalog for our use case

The AI Catalog spec has no concept of org hierarchy or manager-scoped discovery. publisher is a single entity per entry — there's no subtree expansion, no org namespace for multi-tenant disambiguation, and no resolver interface. Our OrgResolver + --manager --org mechanism is an extension the spec doesn't address.

The opportunity

Rather than inventing a parallel ownership schema, OASF could adopt or align owners with the AI Catalog Publisher + TrustManifest model for cross-catalog interoperability, then extend it with:

• alias + org for OrgResolver routing and multi-tenant disambiguation
• The OrgResolver interface and --manager --org query as ADS-layer extensions on top

This would also open the door to the ADS exposing an AI Catalog-compatible endpoint, making OASF records discoverable by any AI Catalog client without additional work.

Worth a discussion with the team on whether alignment here is in scope before the OASF schema PR lands.