Standardize AgentCore id reuse across memory, browser and code interpreter, and make default names collision-safe

> _Migrated from https://github.com/aws-samples/sample-open-agentic-platform/issues/55 — originally opened by @shapirov103 on 2026-08-13T14:20:12Z._

## Summary

The three AgentCore components (`agentcore-memory`, `agentcore-browser`, `agentcore-code-interpreter`) wire themselves to their consumers in two different ways, and their default resource names can collide across clusters in the same AWS account. Both should be fixed once, across all three, rather than per component.

**Sequencing: this is a follow-up to #49 and #54.** It touches all three components and both MCP servers, so doing it inside either PR would widen them. Apply after #49 (browser) and then #54 (code interpreter) merge.

## Problem 1: two patterns for the same job

**`agentcore-memory` passes the id through KubeVela data passing.** From `platform/oam/examples/example-agent-agentcore-memory.yaml`:

```yaml
- name: agentcore-short-memory
type: agentcore-memory
outputs:
- name: memory-id
valueFrom: output.status.atProvider.id
- name: my-agent
inputs:
- from: memory-id
parameterKey: properties.memory.config.memoryId
```

The AWS resource name appears nowhere. It defaults from the component name and the id flows automatically.

**This works.** Verified on `peeks-hub` rather than assumed, because the example's placeholder value would silently pass through if injection failed. The running agent has:

```
MEMORY_CONFIG='{"memoryId":"agents_agentcore_short_memory-WcO63F9gzf",...}'
```

A real id carrying the AWS-generated suffix, not the placeholder.

**`agentcore-browser` and `agentcore-code-interpreter` instead repeat the name as a literal**, once to provision and once in an env var, and the MCP server calls `ListBrowsers` / `ListCodeInterpreters` at boot to turn it into an id. See `example-browser-mcp.yaml` (`browserName` plus `AGENTCORE_BROWSER_NAME`) and `example-code-interpreter-mcp.yaml` (`interpreterName` plus `AGENTCORE_CODE_INTERPRETER_NAME`).

Nothing validates that the two strings agree. A mismatch is not a render error; the pod simply never becomes ready.

The split appears to be an accident of the consumer's shape rather than a decision. The `agent` component has a typed scalar field for `parameterKey` to target (`properties.memory.config.memoryId`), while `mcp-server` has only a generic list:

```cue
env: *[] | [...{ name: string, value: string }]
```

so the equivalent target would be `properties.env[0].value`, which is position dependent. Whether `parameterKey` can index a list at all is **unverified** and is the first thing to establish.

## Problem 2: default names can collide across clusters

All three components derive the same default (`agentcore-browser.cue:22`, `agentcore-code-interpreter.cue:38`, `agentcore-memory.cue:22`):

```cue
let _autoName = strings.Replace(context.namespace + "_" + context.name, "-", "_", -1)
```

Namespace plus component, with no cluster. AgentCore names are unique per **account**, and this platform deploys to a hub and spokes in one account, so the same application in the same namespace on two clusters requests the same name.

The loser does not fail cleanly. It fails with `ConflictException`, and the provider then retries that same create indefinitely, leaving the managed resource `Synced=False` with an empty `atProvider` and therefore permanently unhealthy. That state is observable on this hub today: the interpreter provisioned by the `crossplane-agentcore` chart has been stuck since 2026-05-27 with

```
ConflictException: CodeInterpreter with name 'peeks_hub_agent_core_code_interpreter' already exists in this account
```

while the interpreter itself exists in AWS and reports `status: READY`. The sibling browser resource is stuck the same way with `cannot determine creation result - remove the crossplane.io/external-create-pending annotation`.

`global.clusterName` is already plumbed into the chart (`gitops/addons/charts/oam-agent-components/values.yaml`, sourced from the cluster secret's `aws_cluster_name` annotation), so the fix has no new wiring.

## Proposed work

1. **Establish whether `parameterKey` can target a list element** such as `properties.env[0].value`. This decides step 2.
2. **Give `mcp-server` a stable scalar target if it cannot.** An optional map merged into env, for example `envMap: {[string]: string}`, makes the path `properties.envMap.AGENTCORE_CODE_INTERPRETER_ID`. A map keyed by variable name stays generic, so no AWS specifics enter `mcp-server`, and it is reusable by any MCP server that needs a value from a sibling component. Note `mcp-server.cue` currently contains zero AgentCore references and that is worth preserving: AgentCore-specific parameters on a generic component are what #43 introduced on `agent` and #49 removed.
3. **Accept an id directly in both MCP servers**, for example `AGENTCORE_BROWSER_ID` and `AGENTCORE_CODE_INTERPRETER_ID`, skipping the name lookup when supplied.
4. **Keep name-based resolution as a documented fallback.** It is not redundant: it is the only way to point at a resource the application does not manage, including the built-in `aws.codeinterpreter.v1` and the resources the `crossplane-agentcore` chart provisions.
5. **Publish the id as an output in all three components.** All three already expose it in `customStatus` and gate `healthPolicy` on it (`memoryId`, `browserId`, `codeInterpreterId`), so this is additive.
6. **Update the examples** so each name is written once, and make the browser and code interpreter examples match the memory one.
7. **Include the cluster in `_autoName`** in all three components.

## What this does not change

Adopting data passing does **not** remove the need for retry-forever initialisation in the MCP servers. Knowing the id does not grant permission to use it. On the code interpreter's first cluster deploy the pod logged 13 consecutive `ListCodeInterpreters` `AccessDenied` failures over 65 seconds *after* the interpreter was already `Ready`, because the IAM policy was still propagating. Data passing removes the duplicated string and the `List*` call, nothing more.

## Migration risk to resolve first

Changing `_autoName` changes `spec.forProvider.name` on managed resources that already exist. It needs to be determined whether the upjet-based provider treats that as a replacement (destroying the existing AgentCore resource, and with it any live sessions) or simply errors. Resources that set the name explicitly are unaffected, which covers both the browser and code interpreter examples; the memory example relies on the default and would be affected.

Options if replacement turns out to be destructive: apply the new default only to newly created resources, or accept a one-time recreate during a maintenance window, or leave existing resources pinned by setting the name explicitly.

## Acceptance

- [ ] A single documented pattern for consuming an AgentCore resource id, used by all three components
- [ ] The AWS resource name written once per application, or not at all when the default is used
- [ ] Name-based configuration still available for resources the application does not manage
- [ ] Default names cannot collide between two clusters in one account
- [ ] Migration path for existing resources decided and written down
- [ ] Examples updated and verified end to end, not just rendered

Start by checking whether parameterKey can target properties.env[0].value. Read agentcore-memory.cue, agentcore-browser.cue, agentcore-code-interpreter.cue, mcp-server.cue, and the three example YAML files, then verify how changing _autoName affects existing resources in the upjet provider. Done means the acceptance checklist is met, including end-to-end example verification and a documented migration decision.

Written by the indexing model from the issue text.