Building block 7 · Going further
Live state
A tool list tells Charlie what it can do, never what already exists. Live state fills that gap: Charlie starts each conversation knowing the latest, and your extension's windows and sidebar can save and load without going through the chat.
What you'd use it for
- Make sure Charlie knows your three checklists exist before you ask about one.
- Report whether a database or service is reachable right now.
- Let a window save a ticked box straight away, with no conversation turn and no cost.
- Fill a sidebar list when someone expands it.
In your manifest
From the checklist extension. Each field points to a file in the extension folder.
{
"name": "checklist",
"boot": { "module": "./handlers/boot.js" },
"channels": { "module": "./handlers/channels.js" },
"sidebar": {
"label": "Checklists",
"component": "./build/ChecklistSidebar.js"
}
}The boot line
The boot module returns one short piece of text, or null when there's nothing worth saying. Checklist's version lists what exists:
module.exports = async function boot(ctx) {
await store.sync(ctx)
const checklists = await store.list(ctx)
// Null, not "there are no checklists"
if (checklists.length === 0) return null
const lines = checklists.map(
(c) => ` - "${c.title}" — slug: ${c.slug}`)
return [
`${checklists.length} checklists exist:`,
...lines,
'Read one with checklist__read, using its slug.'
].join('\n')
}Channels
The channels module exports named functions. Your window or sidebar calls them by name with charlie.invoke. Each one gets the payload and a ctx, and whatever it returns goes back to the window.
async function load(payload, ctx) {
return store.load(ctx, payload.slug)
}
async function save(payload, ctx) {
const saved = await store.save(ctx, payload.checklist, {
expectedRevision: payload.expectedRevision,
writtenBy: 'operator'
})
return { ok: true, revision: saved.revision }
}
module.exports = { load, save, list: listChecklists }const result = await charlie.invoke('save', {
checklist: next, expectedRevision: next.revision
})What each part means
| Field | What it does |
|---|---|
boot.module | A file whose default export returns one line of state (or null). Runs on the first turn of every new thread. |
channels.module | A file of named functions your own window, sidebar or top-bar view can call. The export name is the channel name. |
Things to know
- Return
nullwhen empty. A line that says "nothing here" still costs space and gives the model something to reason about.nullkeeps your extension out of the conversation entirely. - Keep it short and fast. The text is cut at 800 characters, with a note saying so. A boot module that takes longer than 5 seconds is dropped for that thread. The hub-database extension gives up after 3.5 seconds and says the status is unknown.
- A failure never blocks the chat. If a boot module throws, Charlie logs it and carries on without that line.
- Boot gets a small
ctx. It hasvault,getSettings,remotePersistenceand the database handlerdbmsPg. Channels get the fullctxa tool gets, exceptrequestUI, because there is no turn to pause. - Unknown channels fail loudly. Calling a name your module doesn't export is an error, so a typo shows up straight away.
- Switched-off extensions do neither. A disabled extension adds no boot line and its channels can't be called.