feat(contacts): remember contacts by the names you use; fix aliases being unusable for non-ASCII names

[ex3lite]

Teaches the server the names you actually use for people, and — separately, and more importantly — fixes a bug that made the existing alias feature unusable for anyone whose contacts are not named in ASCII.

The blocker first

@validate_id checks chat_id against ^@?[a-zA-Z0-9_]{5,}$ before the tool body reaches resolve_entity, so apply_alias never ran for a non-ASCII alias. Verified on the shipped code: send_message(chat_id="чикичев игорь") returns Invalid chat_id, while an ASCII alias reaches the resolver. Every Cyrillic alias is dead on send_message and ~76 other decorated tools today. log_and_format_error masking str(error) compounds it — nothing a resolver says can reach the agent.

Tags without a tag field

The map has always been many-aliases-to-one-id, so a tag is just another alias: save both андрей бекендер and бекендер for one person and either resolves. No tags field, no new write path, no merge semantics, no name-vs-tag ranking. The value becomes {id, name, account} — the name snapshot is what makes a wrong memory visible in list_contact_aliases, which now returns one row per person.

Learning loop, no new tools

An unresolvable reference no longer dead-ends in An error occurred (code: …). It returns a structured instruction — nothing_sent, candidates, known_aliases — telling the agent to ask the user once, save the answer with set_contact_alias, and retry. That wording then resolves silently forever. Four kinds: unknown, confirm (one lookalike), ambiguous (several), stale (saved id no longer resolves → repoint with replace=True). Wired at two shared choke points, so all 95 resolver call sites inherit it.

Only an exact wording sends

This is the load-bearing decision. An earlier revision resolved inflections silently (Андрею бекендеру → the saved андрей бекендер). Adversarial review killed it with evidence: saved леня + a send to Лена resolved to Leonid, иван + Иванов likewise, and 23 common first-name/surname pairs collide. Лена/Леня differs exactly as much as a case ending does, and the ambiguity guard cannot catch it — when the person you meant is not saved, there is only one match and it is the wrong one.

So a lookalike now only suggests: the tool sends nothing and hands the agent the candidate by name for a yes/no. Confirming saves that wording, so a new phrasing costs one question the first time and nothing after. TELEGRAM_CONTACT_FUZZY=0 drops suggestions too. Query tokens must also claim distinct alias tokens — андрей андреев used to match a stored андрей because both words landed on the same token.

Other defects fixed while in there

• save_aliases truncated in place: a partial write destroyed every alias. Now mkstemp + os.replace under an flock, so concurrent saves cannot lose one and a delete cannot be undone.
• load_aliases caught 2 of 5 possible error types; a malformed file took down every chat tool. It never raises now and skips only bad rows. A degraded read refuses to write over the file it could not parse.
• An alias could shadow me, a real @username or a numeric id; both the save and the resolve path now refuse.
• Storage moved out of the install directory to ${XDG_STATE_HOME:-~/.local/state}/telegram-mcp/aliases.json at 0600 (the pattern requested in feat: favorite aliases, incoming event feed (callback mode), rich messages with Premium gating #176); the old file is still read as a fallback.
• Alias write tools were annotated readonly=True while writing shared state.
• alias_key folds case, NFC, ё/е and whitespace, so equal-looking keys stop silently overwriting each other.
• AliasNeedsUser is not a ValueError, because several tools wrap resolution in except ValueError and would mangle the instruction.
• The two resolvers were 60 lines of identical retry logic; they are now one helper, which is where peer-error handling lives.

Testing

58 unit tests for this feature (suite: 256 passed), including a pinned table of 12 inflections that must match and 13 different-person pairs that must not, plus locking, unreadable-store refusal, and shadow guards. Separately, 31 live end-to-end checks against a real account cover unknown → ask → save → send, tag-only wording, lookalike refusal, ambiguity, shadow and repoint guards, stale repointing, deletion, and a real @username staying untouched. Three defects were found by those live checks alone and are fixed here: adjective declensions never matched, ambiguity was labelled unknown, and the stale branch was unreachable on every decorated tool.

🤖 Generated with Claude Code