볼 때만 본다

Dad sends a turn
  panel  -> POST /api/device-look {conversation, turn, kind: canvas}    409 unless ariandel/cinder
  panel  -> send turn {look: {sessionId, turnId}}                      bound once: this turn, this kind
  server    allowlist += exactly one look tool: canvas
  panel  -> GET /api/device-look/{id}   (long poll, <= 10 s each)

Pippa decides to look
  brain  -> canvas({reason, include_guides?, subject?, candidate?})    broker waits <= 20 s
  poll  <-  {request}
  panel  -> host: {type: ariandel:request-canvas, requestId, guides?}  host timeout 4 s
  app       CanvasBridge.answer -> canvasSnapshot()
              flatten(maxEdge: 1568, frame in view) -> JPEG 0.86 on white (+ guides if asked)
  panel  -> POST /api/device-look/{id}/{requestId} {jpeg, captured_at}
  server    0 < bytes <= 2,000,000, JPEG, longest side <= 2048, verify()
  brain  <- tool result: [note text, image/jpeg]                        never stored

Turn ends
  panel  -> abort poll; DELETE /api/device-look/{id}                    later polls: 410

Can't answer: {error: "The canvas could not be read."} -> an error tool result, never a guess

    /// The picture Pippa sees with each turn: the flattened canvas, at most
    /// 1568 px on its long edge, as JPEG. The file name carries the canvas size.
    /// `includingGuides` draws Pippa's guides into the picture (when she asks
    /// to check where they landed), hidden or not; they never enter a layer.
    func canvasSnapshot(includingGuides: Bool = false) -> (name: String, data: Data)? {
        guard let image = try? renderer.flatten(artwork, maxEdge: 1568, visibility: frameInView) else { return nil }
        let overlay = includingGuides ? guides.flatMap { guideImage($0, width: image.width, height: image.height) } : nil
        guard let data = ImageCoding.jpeg(image, quality: 0.86, overlay: overlay) else { return nil }
        return ("canvas-\(artwork.size.width)x\(artwork.size.height).jpg", data)
    }

"""A minimal sketch of a turn-scoped look: the brain asks, the device answers,
and when the turn ends there is nothing left to ask through."""
import asyncio


class Unavailable(Exception):
    pass


class Broker:
    def __init__(self, capture_timeout=20.0):
        self.sessions = {}            # session id -> asyncio.Queue of pending asks
        self.capture_timeout = capture_timeout

    def open(self, turn):             # the panel, before it sends the turn
        self.sessions[turn] = asyncio.Queue()
        return turn

    def close(self, turn):            # the panel, when the turn ends
        self.sessions.pop(turn, None)

    def tools_for(self, turn):        # no session, no tool: she cannot even ask
        return ["canvas"] if turn in self.sessions else []

    async def look(self, turn, reason):           # the brain's tool call
        if turn not in self.sessions:
            raise Unavailable("No canvas is open for this turn.")
        answer = asyncio.get_running_loop().create_future()
        await self.sessions[turn].put((reason, answer))
        try:
            return await asyncio.wait_for(answer, self.capture_timeout)
        except asyncio.TimeoutError:
            raise Unavailable("The device did not return a picture in time. "
                              "Do not assume a view was seen.") from None


async def device(broker, turn, snapshot):          # the panel's long-poll answerer
    while turn in broker.sessions:
        try:
            reason, answer = await asyncio.wait_for(broker.sessions[turn].get(), 0.1)
        except asyncio.TimeoutError:
            continue
        answer.set_result(snapshot())               # straight back into the tool result


async def main():
    broker = Broker(capture_timeout=0.5)
    turn = broker.open("turn-1")
    painter = asyncio.create_task(device(broker, turn, lambda: b"\xff\xd8 fresh JPEG"))
    print("tools this turn:", broker.tools_for(turn))
    print("she looks:", await broker.look(turn, "Check the proportions"))
    broker.close(turn)
    await painter
    print("tools after the turn:", broker.tools_for(turn))
    try:
        await broker.look(turn, "One more peek")
    except Unavailable as error:
        print("between turns:", error)

    silent = broker.open("turn-2")                  # a device that never answers
    try:
        await broker.look(silent, "Look again")
    except Unavailable as error:
        print("no answer:", error)

asyncio.run(main())