Design a unified machine-aware Agent Resource Registry

[mydmdm]

Summary

Add a general, machine-aware Agent Resource Registry to Agenetes alongside Agent Profiles. Huabu mounts the reusable registry into its authenticated Settings and canvas-scoped RFS surfaces. An Agent Profile selects resources by stable ID, and a launch-time resource override may replace that selection before the thread is first realized.

The initial registry is deliberately a small, agent-readable catalogue rather than a general executable-resource protocol. Agent Team Setup is not a resource source in this phase and its preparation path remains unchanged.

Resource record

Every resource uses one minimal versioned record:

interface AgentResource {
  schemaVersion: 1;
  id: string;
  name: string;
  provider: string;
  description: string;
  instructions: string;
}

• IDs are stable, globally unique, human-readable kebab-case values such as huabu-access and web-search; they do not encode kind, provider, machine, or path.
• provider is the stable authority publishing the record, initially huabu or an exact Agentlet machine ID.
• description is the short catalogue summary.
• instructions is natural-language guidance for the agent and may reference runtime variables such as $HUABU_RFS_URL, $AGENTLET_TOKEN, or $AGENT_RESOURCE_DIR, but never contains secret values.
• The catalogue does not persist kind, availability, annotations, requirements, input/output contracts, authorization state, installation state, or structured access methods.

Ownership and persistence

• Agenetes owns the canonical Resource contract, framework-independent registry service, versioned resources.json persistence, Profile resource IDs, generic override semantics, and durable workload snapshots.
• Huabu registers Huabu resources, mounts owner-facing and RFS HTTP adapters, supplies Huabu-required defaults, and applies host authorization policy.
• Agentlet owns its machine resource root, installation receipts, validation, and process environment. It registers or withdraws machine-local records through Agenetes.
• Resource registration is a privileged provider operation. A provider may replace its own ID; another provider receives a conflict.
• Withdrawing a resource does not cascade into Profiles or durable workloads. Resolution fails explicitly when a stored ID no longer resolves.

Agent Profile v2

Resources become a first-class Agent Profile field:

interface AgentProfileBase {
  schemaVersion: 2;
  id: string;
  alias: string;
  agentletId: string;
  workingDirPath: string;
  resourceIds: string[];
  customData?: Record<string, JsonValue>;
}

• Existing Profiles with no per-record version are Profile v1 and migrate to v2 with resourceIds: [].
• The Agent Profile registry file advances from v3 to v4 and rewrites normalized Profile v2 records.
• Create callers do not select a schema version; Agenetes creates v2 records and APIs return v2.
• Manifest-backed Profiles receive the same field for schema consistency, but Phase 1 does not derive resources from Agent Team manifests or alter setup/runtime preparation.

Selection and override

• Profile create and patch accept a bounded, unique list of known resource IDs eligible for the Profile placement.
• A machine-local resource is eligible only when its provider matches the Profile agentlet ID.
• Profile patch replaces the complete resource list.
• Launch resourceIds, when present, completely replaces the Profile selection; [] means no optional resources.
• Huabu unions its required defaults, initially huabu-access and local-resource-management, after replacement. Agenetes does not hard-code Huabu defaults.
• The override is accepted wherever the existing workingDirPath launch override is accepted and only before first realization.
• New workloads explicitly snapshot effective resource IDs. Existing Agent Profile workload v1 snapshots without the field remain readable as resourceIds: []; the driver schema version stays v1.

Discovery

• GET /api/acp/resources is the owner-only global catalogue used by External Agent Profile create/edit UI.
• GET $HUABU_RFS_URL/resources exposes safe catalogue records through the current canvas-scoped RFS boundary.
• Global records use runtime variables rather than persisting a concrete Canvas URL or bearer token.
• The durable external-agent bootstrap identifies the effective selected resource IDs and the catalogue endpoint.
• Catalogue visibility and Profile selection are not invocation authorization.

Local resource management

• Agentlet injects AGENT_RESOURCE_DIR, defaulting under ~/.agentlet/resources.
• Local Skills, tools, connectors, and installation receipts remain machine-owned.
• The Local Resource Management Skill guides user-approved installation, validation, update, and removal.
• Registry records never establish installation or trust by themselves.

Phase 1 acceptance criteria

• Agenetes persists and serves the minimal catalogue through framework-independent operations.
• Huabu mounts Settings and canvas-scoped RFS views.
• Ordinary External Agent Profiles can select resources and replace them at launch.
• Profile v1 to v2 and registry file v3 to v4 migration is covered.
• Effective resource IDs are durably snapshotted while existing workloads remain recoverable.
• Required Huabu defaults survive replacement without being hard-coded in Agenetes.
• Missing, invalid, cross-machine, or withdrawn resources fail explicitly.
• Secrets never appear in Resource, Profile, WorkloadSpec, prompt, log, or client-visible records.
• Agent Team manifests do not implicitly create resources.
• Agent Team Setup, preparation state, Config resolution, workspace materialization, and runtime environment behavior remain unchanged.

Follow-up

#110 registers Huabu-hosted web search and image generation resources and adds scoped invocation. Hosted capability schemas, credentials, authorization grants, quotas, cancellation, audit, and error behavior remain separate from the descriptive Resource record.