io.github.bartek-filipiuk/intent-hub

Release a held or confirmed slot of this session, so the slot is free again. Businesses that host their own agent do not offer this yet and answer `not-supported`.

What this hub can do, in one call: every tool by name, every resource by URI, every prompt by name, the per-client budgets, how to authenticate, the protocol revision and where the documentation is. Takes no arguments, spends no budget and reads nothing: it answers the hub's own constants, so a client that asks it first never has to guess. Called with a key it also answers who that key is.

Confirm a held slot with the customer's name and phone number; this is the booking. Idempotent: confirming the same hold twice books it once and tells the business once. With a linked number (link_phone) you may send `contact` with the name alone and the linked number is used; a different number in `contact.phone` is refused as `phone-mismatch`.

Spend the code that link_phone texted, and tie this agent to that number. Ten minutes and five tries; a wrong code answers `invalid-code` with `attemptsLeft`, and the fifth wrong one throws the code away — call link_phone again for a new one. One number per agent: linking another replaces it.

Find offers from local businesses for what a person asked for. Send their sentence as `text`; the hub parses the trade, the town and the day. An answer with `complete: false` carries a `question` to put to the person: call this tool again with the same `session` and their reply as `text`. An answer with `complete: true` is one finished bidding round: `bids` ranked (price in grosz, slot, business, note) and one `outcome` per business asked. An empty `bids` list is a normal answer; `outcomes` says why. A bid whose `business.active` is true comes from a business whose owner has confirmed it is running; those are ranked above the rest, and cheapest first inside each group.

Read the state of a session: the understood intent and its open question, the bids of the current round and every hold with its present status and link. Use it to pick up a conversation you already have a session id for.

Hold the slot of one bid from this session's round for ten minutes, before asking the person for their details. Answers the hold, the bid it was made from and, when the hub has a public origin, the customer's private booking `link`. Never call it to browse: a hold blocks a real slot and three per client per ten minutes is the budget.

Tie this agent to the phone number of the person it books for: the hub texts that number a six-digit code naming this agent, and `confirm_phone` spends it. Afterwards `confirm_booking` may leave `contact.phone` out — the linked number is used — and every booking made through this key shows up on that person's own list of bookings at /me, next to the ones they made on the site. Ask the person for their own number and never anybody else's: a code arrives on their phone with this agent's name on it. Answers `{ ok: true, sent: true }` whatever the hub knows about the number, and 3 calls per agent per hour is the budget.

Get this agent its own identity, once: answers an `agent` id and a `key`. The key is shown in this answer and never again — keep it and send it as `Authorization: Bearer <key>` on every later call. hold_slot, confirm_booking, cancel_booking need it; finding offers and reading a session do not. With a key the hold and cancel budgets are yours instead of your address's, so two agents behind one address no longer take each other's. 3 registrations per client per day: register once and keep the key, do not mint one per conversation.

Forget the number this agent was linked to. The bookings already made keep it — they belong to the person, not to this agent — and confirm_booking needs a full `contact` again. Answers the same whether there was a link or not.