Make LangChain the default harness, and let a framework Bot call tools back - #33
Merged
Conversation
davidmckayv
requested review from
MikeRyanDev,
guidovizoso and
tylerslaton
as code owners
August 20, 2026 03:52
8 tasks
guidovizoso
previously approved these changes
Aug 20, 2026
`agent-bot` hand-writes the AG-UI protocol and leaves the tool loop to whatever is watching. That is a fine reference and a bad thing to build a deployment on, so the default teammate endpoint is now `agent-langgraph` on 4201: a real framework, running a real loop. The loop moves into the agent, and stays governed. A framework Bot that called an MCP server directly would be a Bot that walked around the grant, the policy and the audit row, which are the product. So it calls back to `/api/agent-tools/call`, authenticated by a shared secret because the caller is a service with no person behind it, and that route goes through the same plugin store as everything else. No secret configured means the route does not exist and the Bot is told so, rather than a deployment quietly accepting anybody who can reach the port. The runtime now sends a remote agent the tools its Bot was granted, on every run rather than configured once, so a grant added or revoked applies to the next run and not after a restart. Two defects fixed on the way. `BOT_MODEL` arrived from compose as an empty string, which is a value, so the agent asked its provider for a model named "" and every run died with "you must provide a model parameter" — read as a broken Bot rather than missing configuration. And the run emitted its answer before the tool calls that informed it, so the surface drew a Bot that spoke first and worked afterwards; tool events are now sent as they happen, with each stretch of prose owning its own message id. Driven in a browser: the LangGraph Bot answered a question about the expense policy, the transcript drew the tool line and then the answer with its source link, and the audit row names risk-analyst calling through the deployment rather than the vendor.
davidmckayv
force-pushed
the
feat/langchain-default
branch
from
August 20, 2026 16:14
aae75d5 to
7e9e0bd
Compare
davidmckayv
added a commit
that referenced
this pull request
Aug 21, 2026
Audited every markdown file against everything that landed today, including the work that was not mine. `docs/coworkers.md` still told people to point `MANAGED_AGENT_AG_UI_URL` at `4200`. #33 made `agent-langgraph` on `4201` the default precisely because the proof-of-concept hand-writes the protocol and leaves the tool loop to whatever is watching, so following that page produced the shape the change moved away from. Three environment variables the server reads were in `.env.example` and nowhere in the configuration reference: `AGENT_STALL_TIMEOUT_MS` from #19, which is the only thing that notices a Bot's stream going silent; `AGENT_TOOL_TOKEN` from #34, without which no framework Bot may call a granted tool back; and `APP_DIST_DIR`, which the container sets so one process serves both halves. Both documentation indexes had fallen behind their own directory and listed neither `deployment.md` nor `releasing.md`. `docs/development.md` gains the migration workflow the checks in #64 now enforce: never hand-edit a generated migration, write a data step with `--custom`, and what to do when `drizzle-kit migrate` hangs and exits non-zero with nothing printed, which is the journal naming a file a rebase renamed. `drizzle-kit check` calls that state fine, because it compares schemas rather than asking whether the journal and the directory agree. The README keeps its shape: what this is, how to run it, how to deploy it, and where to read the rest.
davidmckayv
added a commit
that referenced
this pull request
Aug 21, 2026
Audited every markdown file against everything that landed today, including the work that was not mine. `docs/coworkers.md` still told people to point `MANAGED_AGENT_AG_UI_URL` at `4200`. #33 made `agent-langgraph` on `4201` the default precisely because the proof-of-concept hand-writes the protocol and leaves the tool loop to whatever is watching, so following that page produced the shape the change moved away from. Three environment variables the server reads were in `.env.example` and nowhere in the configuration reference: `AGENT_STALL_TIMEOUT_MS` from #19, which is the only thing that notices a Bot's stream going silent; `AGENT_TOOL_TOKEN` from #34, without which no framework Bot may call a granted tool back; and `APP_DIST_DIR`, which the container sets so one process serves both halves. Both documentation indexes had fallen behind their own directory and listed neither `deployment.md` nor `releasing.md`. `docs/development.md` gains the migration workflow the checks in #64 now enforce: never hand-edit a generated migration, write a data step with `--custom`, and what to do when `drizzle-kit migrate` hangs and exits non-zero with nothing printed, which is the journal naming a file a rebase renamed. `drizzle-kit check` calls that state fine, because it compares schemas rather than asking whether the journal and the directory agree. The README keeps its shape: what this is, how to run it, how to deploy it, and where to read the rest.
davidmckayv
added a commit
that referenced
this pull request
Aug 21, 2026
* Sign in with Google, Microsoft or Okta, whichever a deployment has
One identity provider was a decision somebody else already made. A company
running this has Google or Entra or Okta and is not going to acquire another,
so any one of the three turns sign-in on, several turn on several, and the
sign-in screen draws a button per provider in a fixed order.
Google and Entra are named providers Better Auth knows the endpoints of. Okta
is not one place, so it goes through the generic OAuth plugin against its
issuer, and the plugin is only registered when Okta is configured. They converge
at the browser: one `signIn.social({ provider })` for all three, so the app does
not know which kind it is asking for and a deployment can gain one without a
rebuild.
The provider list moved from the build to `/api/capabilities`. It used to be
compiled into the bundle from the build machine's environment, which was
survivable until the container: one image, built once, knowing nothing about the
deployment that runs it, would have offered a sign-in screen that had never
heard of the provider the operator configured.
Nothing configured now means one administrator without a flag, so a fresh clone
reaches the product without registering an OAuth client first. The lock moved
from a flag to `NODE_ENV`: somewhere other people can reach, an unconfigured
deployment refuses to start and names what to configure, because a public URL
where every visitor is an administrator is silent and looks like it works.
`OPENBOT_SINGLE_USER=true` is how somebody says they meant it.
Two defects found by signing in for real rather than reading the code.
Better Auth 1.7 requires an `issuer` on every account and this schema, written
against 1.6, had no such column. The adapter rendered `where ( = $1 ...)` with
an empty column name and the callback failed with an internal error. Migration
0002 adds it as three statements rather than the one Drizzle generates, because
`ADD COLUMN ... NOT NULL` with no default fails outright on a table that already
has rows, and Google's rows are backfilled with Google's real issuer so they
still match at the next sign-in.
`server/package.json` also asked for `^1.6.27` while 1.7.1 was what resolved,
leaving three copies of the adapter installed. Pinned to what actually runs.
* Make the administrator list mean something after the first sign-in
Two ways a deployment could end up with nobody who can administer it, and no
way back from either.
`INITIAL_ADMIN_EMAILS` was optional. Configure sign-in without it and everybody
arrives as a plain user, nobody sees the admin screens, and nobody can promote
anyone, because the role is written from that list and no route anywhere changes
one. `.env.example` ships it commented out, so copying the example and adding a
provider was enough to do it. Sign-in now refuses to start without it.
The role was also written once, in the create hook. Adding yourself to the list
after you had already signed in did nothing at all: the row said `user`, for
ever. It is now reconciled on every sign-in, which also means an address taken
off the list loses `admin` next time it signs in. `user_roles` is a set and the
guard takes `admin` if any row says so, so reconciling deletes the rows that
should not be there rather than only inserting one, both inside a transaction:
between the two a request on another process would find no role at all and be
refused with a 403 that reads as a permissions bug.
Driven on the real path rather than reasoned about: the same account went
admin, then user with the address removed, then admin again with it restored.
The middle step is what the old hook could not do.
* Make the administrator list a floor, and put each provider's mark on its button
The list and an admin screen have to be able to disagree without one silently
undoing the other. So `INITIAL_ADMIN_EMAILS` is a floor: an address it names is
made an administrator at every sign-in and cannot be demoted, which is the way
back in when the last administrator demotes themselves by accident. Everybody
else is left exactly as they are, because their role is the admin screen's to
decide and a sign-in that rewrote it would make that screen lie the moment they
came back.
That is a change from an hour ago, when sign-in rewrote every role from the list
and would have reverted any promotion made in a screen that does not exist yet.
The buttons now carry each provider's own mark, drawn inline rather than
fetched: this is the one page somebody reaches before they have a session, so a
mark that arrives over the network is one that can be missing exactly when the
page has to look trustworthy, and it asks nothing of a third party from an
unauthenticated page.
Google's guidelines require the standard colour G at its own aspect ratio and
require their button be at least as prominent as any other sign-in option, so
all three are the same size and weight and none of them is the loud one. Okta's
is monochrome, which their guidelines allow: it is not a consumer button anybody
recognises by colour, it is whichever Okta the company uses, and it stays
legible in both themes without a second asset.
* Let an administrator decide who else is one
An environment variable was the only way to grant the administrator role, and
no route anywhere changed one. That is not how a company runs a deployment: the
people who need access arrive after the deployment does.
So a People screen. Everybody who has signed in, the providers they came
through, when they were last here, and two decisions per row.
Removing somebody is both halves or it is theatre. The deny list stops the next
sign-in and deleting their sessions stops the current one, because otherwise a
removed person keeps working until their cookie happens to expire, which can be
days. It is keyed on the email address rather than the user id: deleting the row
is not removal, since the next sign-in through the provider creates it again
with a fresh id and no memory of having been removed.
Three refusals, all enforced on the server and only mirrored in the browser.
Nobody may demote themselves or remove their own access, because either locks
them out of the screen that would undo it, and on a deployment with one
administrator that is the whole deployment. And somebody named in
INITIAL_ADMIN_EMAILS may be neither, because the floor promotes them again at
their next sign-in and the screen would be lying until then.
Every change writes a row. The table holds the current answer; the trail is the
only thing that can say who changed it and when.
Found by driving it: people who had never signed in sorted above people who just
had, because Postgres puts nulls first on a descending order. On a real
deployment that is the whole first screen given to people who have never used it.
* Take a company's own identity provider, by SAML or OIDC
The three configured providers cover a company that uses Google, Entra or Okta.
They do not cover a company that runs its own identity provider, which is most
of the ones that ask, and which cannot be configured up front because the
deployment is built before it knows whose IdP it will trust.
So they are registered while running. An administrator pastes the metadata their
identity team supplied and the provider is stored against an email domain.
Somebody signing in types their address, and the part after the @ decides which
provider they are handed to, so a company mid-merger can run two at once. No
password is asked for and none is checked here.
Registering, changing and removing one is administrator-only. Better Auth guards
those routes with `sessionMiddleware`, which asks only that somebody is signed
in, and that is the wrong bar: registering a provider for a domain means
anybody it vouches for can sign in, so a plain user reaching it could mint
themselves colleagues. The gate sits in front of the handler and is tested.
The sign-in screen grows the email box only when a provider is registered, and
the capability that says so is a boolean rather than a list: naming them would
tell anybody who loads the page which companies use this deployment.
Driven end to end. A registered SAML provider produces a real signed
SAMLRequest redirect for an address at its domain and a 404 for one that is not,
the same delete call answers 403 signed out and 200 as an administrator, and the
sign-in screen adds and drops the email box as the last provider comes and goes.
* Find an address for somebody arriving from Entra, whatever claim it is in
The sign-in flow really is the same for all three: authorization code with PKCE,
discovery, an ID token. Google and Entra run through the same function. The
claims inside that token are where they stop agreeing.
Entra does not always send `email`. Microsoft return it only when the profile
carries an email attribute, and a multi-tenant application may receive no
optional claims at all, because an external user's token is minted by their own
tenant and does not inherit this application's claim configuration. `common`,
the default tenant here, is multi-tenant. Better Auth maps `email` straight
through with no fallback, so on those deployments it arrives undefined.
That is worse here than in most products, because every authorization decision
OpenBot makes about a person is keyed on their address: INITIAL_ADMIN_EMAILS,
the role, the deny list and the People screen all read it. Somebody would sign
in successfully, match no administrator, and land as a plain user with nothing
on any screen explaining why.
So `upn` first, then `preferred_username`, and only if it looks like an address:
the OIDC spec explicitly does not promise that claim is one. If none of the
three is there, nothing is returned and Better Auth refuses the sign-in, which
is a better answer than quietly admitting somebody the deployment cannot
recognise. The reason is logged with the claims that did arrive.
Found by reading the provider Microsoft-side rather than by testing, since
there are no Entra credentials here yet.
* Generate the schema steps, and write only the data step
The issuer migration was one file I had edited by hand after Drizzle generated
it, because the generated `ADD COLUMN ... NOT NULL` fails outright on a table
that already has rows. Editing a generated file is the wrong fix: it leaves a
file that no longer matches what the generator produced.
It is three steps instead, and only the middle one is written:
0002 generated the column, nullable, and the two new tables
0003 custom the backfill
0004 generated the column made required
`drizzle-kit generate --custom` is Drizzle's own mechanism for this, and their
documentation names data seeding as the reason it exists. A generator diffs
schema against schema, so "the rows whose provider is Google get Google's
issuer" cannot come out of one: it is not in the schema.
The generatable alternative is a column default, and it is wrong rather than
merely inelegant. Every existing Google account would take the placeholder, stop
matching `https://accounts.google.com` at that person's next sign-in, and Better
Auth would create them a second account.
Driven both ways with `drizzle-kit migrate` itself rather than by hand: from
empty, and against a database already holding Google, credential and Microsoft
accounts, where the three rows come out with Google's real issuer and the
synthetic form for the rest.
Worth knowing for the check that landed in #64: `drizzle-kit check` reports
"Everything's fine" when a journal entry names a migration file that does not
exist, which is a state a rebase can produce. It cost an hour here. The drift
probe does not catch it either, since both look at schemas rather than at
whether the journal and the directory agree.
* Say what sign-in does, everywhere it is documented
The configuration reference still described Google as the only provider and
described `INITIAL_ADMIN_EMAILS` as optional, which is now a start-up failure.
It carries all three providers, what each needs, the callback URL to register,
and why the administrator list is required.
The architecture notes gain the parts a reader cannot infer from the code: that
one resolver answers both questions a run asks about a person, that the
configured list is a floor rather than a one-off, that registering an identity
provider is administrator-only where the upstream plugin asks only for a
session, and that removing somebody denies the address rather than deleting the
row, since deleting it is not removal.
Two lines in the README's feature list, because sign-in and deciding who gets in
are now things the product does rather than things it lacks.
The generated Drizzle snapshots are formatted, which is what the committed ones
already were: `drizzle-kit generate` writes them without a trailing newline and
the format check refuses that.
* Bring the docs up to what is actually merged
Audited every markdown file against everything that landed today, including the
work that was not mine.
`docs/coworkers.md` still told people to point `MANAGED_AGENT_AG_UI_URL` at
`4200`. #33 made `agent-langgraph` on `4201` the default precisely because the
proof-of-concept hand-writes the protocol and leaves the tool loop to whatever is
watching, so following that page produced the shape the change moved away from.
Three environment variables the server reads were in `.env.example` and nowhere
in the configuration reference: `AGENT_STALL_TIMEOUT_MS` from #19, which is the
only thing that notices a Bot's stream going silent; `AGENT_TOOL_TOKEN` from #34,
without which no framework Bot may call a granted tool back; and `APP_DIST_DIR`,
which the container sets so one process serves both halves.
Both documentation indexes had fallen behind their own directory and listed
neither `deployment.md` nor `releasing.md`.
`docs/development.md` gains the migration workflow the checks in #64 now enforce:
never hand-edit a generated migration, write a data step with `--custom`, and
what to do when `drizzle-kit migrate` hangs and exits non-zero with nothing
printed, which is the journal naming a file a rebase renamed. `drizzle-kit check`
calls that state fine, because it compares schemas rather than asking whether the
journal and the directory agree.
The README keeps its shape: what this is, how to run it, how to deploy it, and
where to read the rest.
* Tell the image check it meant to run without sign-in
The check boots the container with no identity provider, and the image sets
NODE_ENV=production, where that combination now refuses to start rather than
serve a deployment on which every visitor is an administrator. So the check has
to declare it, which is what the flag is for.
It was passing `OPENBOT_DEV_NO_AUTH=1`, which the code has never accepted:
both the old flag and the new one compare against the exact string "true". It
did nothing, and nothing noticed, because before this branch a deployment with
no provider still started and answered on an unauthenticated route. The refusal
turned a silent no-op into a visible failure, which is the check working.
Reproduced locally with the same command the job runs: answers on
/api/capabilities in four seconds, nothing respawning after fifteen, and the
`eventsource` import error that appeared in the failing log is absent, since it
was the crash loop rather than a fault of its own.
* Put the upgrade note where somebody upgrading will find it
Two configurations that start today refuse to after this, and both were buried
mid-paragraph in Added and Changed. They are four lines at the top of Unreleased
now, saying what to set rather than what used to happen.
Rebased onto #68, which took the deployment's environment away from a Bot's
shell. Checked on the running computer rather than trusting the tests:
`GOOGLE_OAUTH_CLIENT_SECRET`, which this branch introduces, is absent from a
command's environment without anybody having added it to a list. That is the
allowlist earning its shape.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
agent-bothand-writes the AG-UI protocol over the raw OpenAI SDK, 235 lines, with its own tool loop. It is a fine reference and a bad thing to build a deployment on, and it was the default:MANAGED_AGENT_AG_UI_URLpointed at it on 4200, so the Bot we ship as the example of "bring your own" was the hand-rolled one while the real framework sat unused on 4201.The default is now
agent-langgraph: real@langchain/langgraph, running a real loop.agent-botstays in the tree as the reference it always was.This also closes the regression #31 disclosed. A framework Bot runs its own loop in its own process, which is the honest shape, but it must not have a route to a vendor that goes around this deployment. So it calls back to
/api/agent-tools/call, which goes through the same plugin store as everything else: same grant check, same policy, same audit row. Remote Bots have MCP tools again.The runtime sends a remote Bot its granted tools on every run rather than at configuration time, so a grant added or revoked applies to the next run instead of after a restart.
Taken from
CopilotKit/openkai(bc246d4), minus its visitor demo, withOPENKAI_/x-openkai-renamed and the refusal marker from #31 applied to this path too.Two defects it also fixes
BOT_MODELarrived from compose as an empty string, which is a value, so the agent asked its provider for a model named""and every run died with "you must provide a model parameter". That reads as a broken Bot rather than as missing configuration. Compose now defaults it.Where it runs
AGENT_TOOL_TOKENis set, so a deployment that has not configured it refuses rather than accepting anybody who can reach the port.Boundary and audit
pluginStore.callTool: grant, then policy, then audit, then the vendor.Known weakness, and the next PR
The actor on this path is not trustworthy yet.
/api/agent-tools/callreadsactorIdfrom the request body and falls back to"agent". Two consequences, both visible in the audit row I captured below:agent.The trail is the product, so a forgeable trail is worse than a thin one. The next PR replaces the shared secret with a per-agent token plus a signed, expiring run assertion that names the Bot and the person, and refuses a call whose assertion does not match the token presenting it. Landing immediately after this one.
Proof
Driven in Chrome.
agent-langgraphrebuilt and started on 4201,AGENT_TOOL_TOKENset,search_notesgranted to Risk Analyst through/admin/plugins.mcp.call_succeeded,notes/search_notes, botrisk-analyst, allowedtrue. Actoragent, which is the weakness above.401with no token,400with the token and no body.format:check,lint,typecheckclean. 665 pass, 5 skip, 0 fail.