feat(context): abbreviate UUID observation refs to 8-char in inject panel

[alessandropcostabr]

Why

Full UUID observation refs are the worst case for the tokenizer in the inject panel — the hex + hyphen pattern fragments into ~17 tokens per ref, for no practical gain (the model retrieves by title/semantic search, not by pasting the ref). This came up on Discord re: server-beta where ids are Postgres UUIDs.

What

When fetch-by-id is unsupported — i.e. server-beta / Postgres UUID mode, where the inject ref isn't a fetch handle — observation refs are abbreviated to their 8-char prefix (3c4b2513-… → 3c4b2513), and the legend switches from get_observations([IDs]) to "mem-search by title/context (short refs are display-only)". The full UUID still lives in observation_search results, where tokens aren't the bottleneck.

Gated by a new optional ContextConfig.fetchByIdSupported:

• Defaults to true → no behavior change for existing setups.
• Numeric (SQLite) ids are never abbreviated (they remain fetchable).
• Set it false in the server-beta context build to enable the short refs.

Small helper formatContextReferenceId(id, config) in formatters/id-display.ts; wired into the Agent/Human formatters and HeaderRenderer.

Notes

• Backward compatible (opt-in via the flag).
• bun test tests/context/formatters/agent-formatter.test.ts → 46 pass / 0 fail (added 6 tests: legend toggle + helper behavior).
• tsc --noEmit clean for the touched files.

🤖 Co-authored with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[greptile-apps]

Greptile Summary

This PR adds opt-in UUID abbreviation for observation refs in the inject panel: when fetchByIdSupported is set to false in ContextConfig (targeting server-beta / Postgres UUID mode), UUID ids are trimmed to their 8-char prefix and the legend switches to a title/semantic-search hint, reducing tokenizer cost without changing behavior for existing SQLite setups.

• New formatContextReferenceId helper in id-display.ts gates abbreviation behind config.fetchByIdSupported === false and a UUID regex, leaving numeric ids and the default (undefined) path unchanged.
• renderAgentLegend and renderHumanContextIndex are wired to fetchByIdSupported; table-row and full-observation renderers in both formatters now call the helper.
• Two pre-existing issues from earlier review rounds remain unresolved: Observation.id is still typed as number despite UUID strings flowing through it in server-beta mode, and renderAgentFooter still hardcodes get_observations([IDs]) regardless of the flag — a direct contradiction of the new legend wording when fetchByIdSupported: false.

Confidence Score: 4/5

Safe to merge for standard SQLite setups; server-beta activation carries two unresolved contradictions that should be fixed before enabling the flag in production.

The core helper and legend wiring are correct, but renderAgentFooter still tells the model to call get_observations([IDs]) even when the legend has already told it those refs are display-only — a direct in-panel contradiction for any caller that sets fetchByIdSupported: false. Additionally, Observation.id is typed as number while UUID strings will flow through it at runtime in server-beta mode, masking a type error that TypeScript cannot catch.

src/services/context/formatters/AgentFormatter.ts (renderAgentFooter not updated) and src/services/context/types.ts (Observation.id still number)

Important Files Changed

Filename	Overview
src/services/context/formatters/id-display.ts	New helper that abbreviates UUID ids to their 8-char prefix when fetchByIdSupported is false; regex and slice logic are correct, and the strict === false guard ensures backward compatibility when the flag is omitted.
src/services/context/types.ts	Adds optional fetchByIdSupported to ContextConfig (backward compatible); Observation.id remains typed as number while the feature relies on UUID string ids flowing through this field in server-beta mode — a type/runtime mismatch flagged in a previous review and still unresolved.
src/services/context/formatters/AgentFormatter.ts	Legend, table rows, and full-observation headers correctly use formatContextReferenceId; however renderAgentFooter still hardcodes get_observations([IDs]) and is not wired to fetchByIdSupported — a contradiction noted in a prior review that remains unresolved.
src/services/context/formatters/HumanFormatter.ts	renderHumanContextIndex correctly switches its drilldown hint based on fetchByIdSupported; table rows and full-observation rows properly use formatContextReferenceId; renderHumanFooter still mentions 'access memories by ID' but this is the developer-facing terminal display only.
src/services/context/sections/HeaderRenderer.ts	Correctly derives fetchByIdSupported from config and threads it into renderAgentLegend and renderHumanContextIndex; agentContextIndex remains an empty stub so no change needed there.
tests/context/formatters/agent-formatter.test.ts	Adds 6 well-structured tests covering legend toggle behavior and all four formatContextReferenceId branches (UUID/non-UUID × supported/unsupported); tests are clear and complete.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[renderHeader / table row] --> B{forHuman?}
    B -- No --> C[Agent path]
    B -- Yes --> D[Human path]

    C --> C1[renderAgentLegend\nfetchByIdSupported]
    C --> C2[renderAgentTableRow\nobs, time, config]
    C --> C3[renderAgentFullObservation\nobs, time, detail, config]

    D --> D1[renderHumanContextIndex\nfetchByIdSupported]
    D --> D2[renderHumanTableRow\nobs, time, config]
    D --> D3[renderHumanFullObservation\nobs, time, detail, config]

    C1 --> E{fetchByIdSupported?}
    D1 --> E

    E -- true / default --> F["Show full ID\nLegend: get_observations([IDs])"]
    E -- false --> G["Abbreviate UUID to 8-char\nLegend: mem-search by title/context"]

    C2 & C3 & D2 & D3 --> H[formatContextReferenceId\nid, config]
    H --> I{fetchByIdSupported === false\nAND UUID?}
    I -- Yes --> J[id.slice 0 to 8]
    I -- No --> K[String id unchanged]

    C --> L[renderAgentFooter ⚠️\nNOT wired to fetchByIdSupported\nstill says get_observations IDs]

Loading

_{Reviews (2): Last reviewed commit: "feat(context): abbreviate UUID observati..." | Re-trigger Greptile}