Seamless agent loop: resolve Sketchi diagram URL to latest share + versioned diff

[anand-testcompare]

Problem

When using an AI agent (OpenCode) to do the full loop:

1. create diagram,
2. user edits in Sketchi,
3. agent pulls latest and summarizes differences,

we currently have to manually provide a direct Excalidraw share URL each time. A stable Sketchi diagram URL alone is not enough for the agent workflow today.

Example stable URL:

• https://www.sketchi.app/diagrams/41339bdb748c32de972632885ed64b43

In practice, the agent had to be given this direct share URL to see updates:

• https://excalidraw.com/#json=D558gpAi2patYU2Zu4Gyu,1xwTOiOroKyCv42vyJXN0Q

Why this is not seamless

• Identifier mismatch: user has Sketchi diagram URL (/diagrams/<id>), tooling expects Excalidraw #json=<id>,<key> share URL.
• Auth/access boundary: fetching https://www.sketchi.app/diagrams/<id> in agent context returns sign-in flow, not latest diagram payload.
• Missing resolver primitive: no API/tool to resolve diagramId -> latest share URL + version metadata.
• Missing first-class diff primitive: agent can inspect one diagram, but no built-in version-aware semantic diff path.
• Error ergonomics: current failure can surface as generic parse/500 style errors (hard to distinguish from auth vs bad link).

Desired interaction pattern

User should be able to say:

• "Pull latest from https://www.sketchi.app/diagrams/<id> and summarize what changed."

Agent should be able to:

1. Resolve the stable Sketchi URL to latest version/share,
2. Export latest PNG locally,
3. Compare against prior local snapshot/version,
4. Return semantic + visual diffs.

No manual share-link handoff in normal flow.

Proposed solution

P0: Resolve latest from Sketchi URL/ID

Add a resolver endpoint (or equivalent SDK function):

• GET /api/diagrams/:id/latest

Returns at least:

• diagramId
• version
• updatedAt
• excalidrawShareUrl (or equivalent export descriptor)
• pngUrl (optional but useful)
• contentHash

P0: Agent-friendly one-shot pull

Add tool/API operation:

• diagram_pull_latest({ sketchiUrl | diagramId })

Behavior:

• resolves latest version,
• exports PNG,
• returns local path + metadata (version, hash, updatedAt, source URLs).

P1: Version listing + diff support

• GET /api/diagrams/:id/versions
• optional: GET /api/diagrams/:id/diff?from=<v>&to=<v>

Diff should expose both:

• structural/semantic changes (nodes/transitions/labels),
• visual/layout deltas (positioning/routing/readability implications).

P1: Better errors

Standardize actionable errors:

• DIAGRAM_NOT_FOUND
• AUTH_REQUIRED
• UNRESOLVABLE_SHARE
• UNSUPPORTED_URL

with hint text for fallback.

P2: Local sync helper (nice-to-have)

Agent-side cache contract (e.g. .memory/sketchi-sync.json):

• remembers last seen version/hash per diagram URL,
• enables "pull latest + summarize changes" as a single command.

Acceptance criteria

• Given only https://www.sketchi.app/diagrams/<id>, agent can fetch latest diagram without manual share URL.
• Agent can detect whether there are changes since last seen version/hash.
• Agent can produce a concise semantic+visual change summary.
• Failure states are explicit and actionable (no opaque 500 for common auth/URL mismatch cases).

Context

This is specifically to support a smooth OpenCode <-> Sketchi iterative workflow for architecture/state-machine diagram edits and review.

[anand-testcompare]

the reason for the 'quick diff' is we ultimately want to be able to communicate changes the human made in the excalidraw diagram to the agent. webhooks or similar would be ideal so it could auto trigger, but idk how to cleanly engineer that rn without it potentially disrupt ongoing state or know when an update is 'finished'