Flow Builder Extension

Shira is the KeenAgents Flow Builder — a VS Code extension whose canvas is where you draw a flow as boxes (nodes) wired together by edges. Instead of writing the whole agent by hand, you drag nodes onto the board, configure each one in a settings panel, and connect them into the step-by-step logic the agent will run.

The extension does four jobs: it scaffolds a project, detects it, connects it to a space, and deploys it — plus it hosts the two debuggers. It holds no agent logic of its own; the behaviour lives in the flows and scripts you author on the canvas and in your project files. Everything you need to build, deploy, and debug a flow lives at this level — you never touch the platform's internals.

Install the Shira Flow Builder extension in VS Code. It adds a Shira Flow Builder view to the activity bar (this is where you scaffold, connect, and deploy) and a companion Breakpoints view beside it. A Toggle Theme button in the view's title bar switches the canvas between dark and light.

The panel also shows a Models chip — a count like "22 models". That roster comes from a model list you paste into the extension's settings; it powers the model picker inside the LLM node so you choose from the providers and models your organization allows. An empty setting shows none.

A project connects to a space through one small file — .vscode/keen.json — with exactly three string fields. The scaffold writes placeholders; Connect refuses to run until you replace all three with real values.

{
  "server": "https://localhost",
  "space":  "cmsm8rezw0000kr7wmyg4pkwb",
  "token":  "5214f5db-0e45-435d-af4f-377592548a59"
}

server

The base URL of your KeenAgents instance — https://localhost for a local sandbox, or https://your-domain otherwise. It is also the host the debuggers attach to. A self-signed certificate is accepted only for a local https://localhost; any other host needs a valid HTTPS certificate.

space

The AI Space ID — copy it from the space's page in the admin console. This is where your deployed code lives, so every deploy lands in exactly one space and can only touch the flows that belong to it.

token

The space's deployment token — copy or reset it on the space's page in the admin console. It is the credential that authenticates a deploy; resetting it retires the old one, so only whoever holds the current token can deploy.

Connect exchanges the token and space id for a short-lived session held in the extension's memory. Reloading the VS Code window drops that session, so you simply Connect again — nothing is lost. A status-bar item shows Connected / Not connected at all times.

The panel's three buttons light up in order — that sequence is the whole path from nothing to a live project:

1. Create Project. Enabled only when the open folder is empty. It scaffolds the project skeleton (below); the panel then flips to "— detected".
2. Fill in keen.json. Replace the three placeholders with your server, space id, and deployment token.
3. Connect. Enabled once a valid project is detected and keen.json is filled. It connects to the target and the button becomes Disconnect.
4. Upload Project. Enabled once connected. It sends your project into the space; the platform scans it for unsafe code and, if clean, promotes it live — your agents now run the new version. There is no restart to schedule.

The first upload is explicit; after that, auto-sync re-uploads on every save (briefly debounced), so your edits keep flowing to the sandbox as you work. If the scan rejects the project, the reason appears in the extension's output — fix it and re-upload. Deploying is entirely the panel's Connect → Upload over HTTPS; there is no command line or package script to run.

A .flow file opens in the canvas — a pan-and-zoom board. Open the node palette, drag a node onto the board, and it appears as a titled card with connection dots. Drag from a node's out dot to the next node's in dot to wire an edge. Each card carries a drag handle (to move it), a Settings toggle (to open its fields), and a Rotate control (cosmetic — it just moves where a dot renders).

The Shira Flow Builder view holds the read-only settings chips (theme, model count) and the three lifecycle buttons. The Breakpoints view lists the node breakpoints you've set, grouped one row per flow file; clicking a leaf reveals and centres that node on the canvas. You set a node breakpoint by selecting a node and pressing F9. Debugging attaches to a sandbox environment only — see the Debugging page.

Create Project writes this skeleton into an empty folder. Structural separation isn't cosmetic: where a file lives decides what it is.

.vscode/
  keen.json          ← your deploy target (you fill this)
  settings.json      ← empty placeholder
src/
  flows/
    Project.flow     ← your first flow (opens in the canvas)
  scripts/
    init.js          ← script bodies for Script nodes
    tools/           ← script-backed tools an agent can call
  keen-tools.json    ← the tool registry
package.json         ← name, version, "type": "module"

src/flows/

Your flows, as .flow files. This folder is flat — only top-level, PascalCase files. Each file is one flow, named the same way you'll name it on the agent. Keeping each flow in its own file is what lets flows call each other by name and be reused.

src/scripts/

The JavaScript bodies for Script nodes. A Script node's path names a file here (e.g. init.js). This folder is scanned recursively, so you may organise scripts into sub-folders.

src/scripts/tools/

The reserved home for script-backed tools — a callable tool whose implementation is a script lives here, which is what marks it as a tool as opposed to ordinary Script-node code.

src/keen-tools.json

The tool registry — one entry per tool the agents may call, each naming the tool's name, whether it is a flow or a script, and where it runs. What the model is told about a tool is authored into the agent's system prompt, not here.

package.json

Carries "type": "module", which makes your script files ES modules — that's why every script uses export const exec. There are no deploy scripts here; deploying is the extension's job.

A folder is a valid project only when all five markers exist — .vscode/keen.json, src/keen-tools.json, package.json, src/flows/, and src/scripts/. You rarely build one giant flow: split logic across several .flow files and connect them by name, exactly as you split code into functions.

• The names must line up with the agent. A flow's file name and its start node's label must exactly match the Start Flow and Start Node set on the agent in the admin console — both PascalCase. A name that's valid in shape but not present in the deployed project leaves the agent with nothing to run, so it never responds. Decide the names once and use them in both places.
• Deploy first, then debug. Both debuggers attach to the code as it runs on the sandbox, so Connect and Upload before you set breakpoints. Debuggers are a sandbox-only feature — a production deployment doesn't expose them.
• The session is in-memory. Reloading the window drops the connection; reconnect and carry on. Deploying is Connect → Upload over HTTPS — never a command line.