Connector chats and hand-offs

Connectors you build or describe yourself, Connect Anything and Connect Any API, have a conversation of their own, where the connector's Mind works on the code or the recipe. A Lake Builder chat can hand connector work over to that thread, follow it, and pick the work back up from the report that comes home. This page covers the thread, the hand-off and the report. The builder itself is described in Warehouse Builder and Lake Builder, and what it can do with connectors in Manage connectors from a chat.

The connector's own thread

• There is one conversation per connector: your own messages, and any work a builder chat hands over, all go into that same thread.
• The Mind in it is the connector's own: the Meltano Mind on a Meltano connector, or the ANY API Mind on a native one. It reads and edits the connector's files or recipe, tests it, and can run a sync. Its step cards are described in Connector operations and data access in chat.
• Open the thread beside the connector with the AI Assistant panel, or from any hand-off or report card with Open connector. The panel itself is covered in The AI assistant.
• The thread runs one turn at a time, and it keeps its own change acceptance mode: Manual or Auto-accept only. Unrestricted is not offered for a connector chat; see Change acceptance for the assistant.

Hand work to a connector Mind

Ask the Lake Builder to hand the work over when the fix belongs to the connector's code or recipe.

1. In the Lake Builder chat, describe the problem and ask for the hand-off.
2. The chat shows a Hand off to connector Mind card, carrying the brief the builder wrote for the connector Mind and the button Open connector. Its line reads "The Meltano Mind works on this in the connector's own thread.", with the ANY API Mind in place of Meltano on a native connector.
3. The brief is posted into the connector's thread, opened by Hand-off from the Lake Builder Mind, and the connector Mind's turn starts there at once.
4. Follow the work with a wait, or end your turn and let the report find you.

• In a Manual chat the hand-off is itself held first, like any other lake change: decide it on the approval card, and the work starts after that. See Change approval in a builder chat.
• Nothing counts as finished before the report arrives.

When a hand-off is refused

A hand-off starts only while the connector's thread is free and needs nothing from you. Otherwise the card reads Refused, with the reason in place of its summary. Each message names the connector's own Mind at the start:

• The thread is busy: "the connector Mind's thread is busy (what holds it); try again when it is free." It is usually a turn already running there, or a person holding the thread with the reason. Wait for the turn to end, then ask again.
• The connector Mind is waiting for you there: "the connector Mind is still waiting for the user in its own thread (what it needs). Ask the user to answer it there first, then hand off again." What it needs is an approval, a question or connector secrets. Open the connector, finish that step, then ask again.
• The thread was taken at the last moment: "the connector Mind's thread was just taken by someone else; try again in a moment." Ask again.

Follow the work

• While the connector Mind works, the chat follows it with a Waiting for connector Mind card that streams what it is doing, with the elapsed time.
• Stop waiting ends only your wait: the connector Mind keeps working in its own thread, and its report still reaches the conversation when it finishes. Stops and aborts in general are described in Stop and abort runs in chat.
• You do not have to stay. End your turn, or leave the chat: the report is delivered into the conversation by itself, and the chat continues from it.
• If a wait runs out of time, the card reads Still working. The work goes on, and the report still arrives.

Read the report

• The report arrives as a card headed Report from the Meltano Mind (or the ANY API Mind), with the connector's name on it and Open connector to go there.
• The card carries a state badge: Working, Waiting for you, Finished, Failed or Stopped, with how long the work took.
• A report carries the connector Mind's reply and a Tools it ran list, which counts the earlier calls it does not show one by one.
• Waiting for you means it needs something from you in its own thread. The card quotes it: "Waiting for you in the connector's thread: what it needs."
• When the report lands, the chat wakes and continues from it: the Lake Builder reads what was changed and published, then does the lake side, such as a schema sync, a re-import or a load. If the chat was stopped, the report still lands, but the builder does not continue from it.
• A very long reply is clipped in the middle, and the omitted length is marked.

When the connector Mind waits for you

• Waiting for you is a pause in the connector's own thread: the connector Mind needs an approval, an answer to a question, or secrets. Open the connector and finish that step there.
• A secrets request opens the vault with the names it needs; the request card and its states are described in Connector operations and data access in chat. Connector approvals are on Approve or reject connector changes.
• Save the values it asked for, and the waiting connector turn resumes by itself. You do not need to send a message.
• Secret values never enter the chat history: store them in the vault, and a value pasted into a chat moves there too, leaving a <redacted:NAME> marker in its place. See Connector secrets.

Roll back or restore what the connector Mind changed

• Every change the connector Mind makes is a version, and a connector's conversation carries roll back and restore controls on its messages. Use them to undo a change that went wrong, and to put it back.
• The controls exist only in a connector's conversation. The versions themselves, the notes a roll back leaves and the wording of the buttons are on Roll back and restore connector versions; the editor's own version list is on The connector code editor.

If the platform restarts mid-hand-off

• An open hand-off is not lost when the platform restarts: the platform picks it back up, and the report still arrives.
• If the restart interrupted the connector Mind's turn itself, the hand-off ends as Failed, and the report carries the line "the connector turn stopped before it finished (it was interrupted, e.g. by a server restart)". Read its reply, then hand the work off again, or continue in the connector's thread.
• The restart notice a chat itself shows, with Retry and Continue, is described in Chat states and recovery.

Questions, answered

Can a connector have more than one conversation?

No. There is one conversation per connector: your own messages and work handed over from a builder chat all go into it.

Can I write in the connector's own thread myself?

Yes. Open the connector and write in the AI assistant beside it, or use Open connector on a card. Your messages and hand-offs share the one thread, and it runs one turn at a time, so wait for the current turn to end before you send.

Why was my hand-off refused?

Usually because the connector's thread is busy with another turn, or because the connector Mind is waiting for you there with an approval, a question or a secrets request. The card reads Refused and names the reason. Free the thread or answer it there, then ask the Lake Builder to hand the work off again.

The card says "Waiting for you". What should I do?

The connector Mind needs something from you in its own thread. Open the connector and give it that: decide the approval card, answer the question, or store the values the secrets request asks for. If the hand-off is still open, its report arrives when the work finishes.

Does the connector's thread continue by itself after I save the secrets it asked for?

Yes. Saving the values a secrets request asked for resumes the waiting connector turn by itself; you do not need to send a message. The values never pass through the chat history.

Does the connector Mind keep working after I stop waiting?

Yes. Stop waiting ends your wait in the chat only; the connector Mind keeps working in its own thread, and its report still reaches the conversation when it finishes. Stopping a wait never ends background work.

Do I need to keep the chat open for the report to arrive?

No. The report is delivered into the conversation when the connector Mind finishes, and the chat continues from it, whether or not you are watching. Open the chat later to read what came back.

Who finishes the lake side of the hand-off?

The Lake Builder chat that handed the work over. The connector Mind works on the connector itself; the lake side, such as a schema sync, a re-import or a load, is done by the builder when the report comes back. Ask it for those steps if it stops short.

A hand-off went wrong. Can I undo its changes?

Yes. Every connector change is a version, and the connector's conversation carries roll back and restore controls on its messages. See Roll back and restore connector versions.

What does it mean when the report says the connector turn was interrupted?

The platform restarted while the connector Mind was working, so its turn stopped before it finished; the hand-off ends as Failed with the interrupted line. The report is the signal to continue: hand the work off again, or finish it in the connector's thread.