Stop everything and the off-switch¶
Two ways an agent ends at once: the person stops it (the emergency stop), or the organisation turns it off. Both need the server of core 0.7.1 or later for the server's part; without it the SDK still does what it can in the browser.
Stop everything¶
agent.stopAll() (.NET: StopAllAsync()) is the emergency stop:
- Every running turn in every open chat stops the way the chat's own Stop button does. The turn ends as stopped (its stream throws an
AbortError, the transcript sayscancelled), a tool call that waits for the person's answer is answered no (the transcript and the server's record say so, with the reason "Stopped."; a call the gateway holds is told no), and no further tool call of the turn runs. One chat alone:chat.stop()(.NET:ChatSession.Stop()), which returns whether a turn ran. - Every grant the agent holds for the person ends: the server's grants (for a time, for a stretch of work, plan, Bypass) and each open chat's "for this chat" approvals.
- What the person allowed always stays. It is their saved preference, not authority that runs;
resetApprovals()forgets it.
The part in the browser always happens, also offline. The server is told after, one grant at a time; a grant it could not be told about is tried once more and, if that fails, counted: it ended in the browser at once (no call runs under it from now on, whatever the server later says) and ends at its time on the server. The stop never waits long for a slow server.
stopAll() returns a StopAllResult with turnsStopped, grantsEnded (the server's grants and the chats' approvals, including those the
server was not told about), chatApprovalsEnded and grantsNotTold; nothingRan(result) is true when the stop found nothing to stop. For an
app with several agents, FadenstackAgent.stopAll(agents) (.NET: FadenstackAgent.StopAllAsync(agents)) stops them all in the browser first
and then tells the servers; the result is the sum (addStopResults).
The control for a toolbar or tray¶
StopEverythingViewModel (@fadenstack/ui; .NET StopEverythingViewModel) takes the agents as a function, because they come and go, and
has stop(), isBusy and resultText: "Stopped 2 chats and ended 3 grants.", "Nothing was running." or "Stopped. The server could not be
told about 1 grant; it ends at its time." There is no confirmation: it is the emergency stop. StopEverythingButton in
@fadenstack/ui-react and @fadenstack/ui-vue is an icon button named "Stop everything" with a tooltip, and the result line, in en, de,
fr, es and zh-Hans.
A refused sign-in ends the turn¶
When the token provider's refresh is refused during a turn (the sign-in ended, the device was signed out, the grant is gone), the turn ends
at once with FadenstackSignInRequiredError (.NET: FadenstackSignInRequiredException), and no tool call of that turn runs after the
refusal; before this, a tool's error result let the next call of the turn run. The chat panel then shows the sign-in again (ASVS 5.0 V7,
session ending).
Access tokens are short¶
Core cuts the agent access token to 300 seconds at most. The SDKs refresh from expires_in, 30 seconds ahead, and assume no
lifetime. A device signed out stops within one token's life; an agent turned off, a person deactivated or a sign-in ended stop at the next
request.
The off-switch¶
An administrator can turn an agent off in the console. From then on every agent route but the profile, the events
and the manifest answers 403 agent_disabled ("Your organisation turned this agent off."), for everyone, and the server has ended the
agent's grants (revoked_by: agent_turned_off).
- Client:
ErrorCodes.agentDisabled,FadenstackApiError.isAgentDisabled,isAgentDisabled(error)(.NET:ErrorCodes.AgentDisabled,IsAgentDisabled);AgentProfile.enabled(true when the key is missing, as from an older server); the outcome"agent_disabled"(.NET:ChatOutcome.AgentDisabled). - Agent:
agent.turnedOffwithagent.onTurnedOffChange(listener)(.NET:TurnedOff,TurnedOffChanged). It turns true when the profile at start saysenabled: false, or any agent route answersagent_disabled: chat,tools/check, approvals, grants, models, tools, skills, user, provenance. At once the running turns stop and the grants end here (as in "Stop everything", without asking the server), and: - a new turn is refused without a request, with the outcome
agent_disabledand the sentence above as its notice (TURNED_OFF_TEXT); - nothing retries: no further request goes to any agent route (they fail in the browser with the same error), no back-off, no reconnect, no background refresh of the profile or the grants;
- the client events and the manifest are still sent;
- someone the agent does not let in still gets
agent_not_grantedoragent_retired, as before. - Try again:
agent.checkAgain()(.NET:CheckAgainAsync()) reads the profile, the one route the server answers for an agent that is off, and clearsturnedOffwhen it saysenabled: true. The SDK reads it again only at start and on this call. - The chat panel shows the sentence with a "Check again" button, disables the composer, and ends the turn that hit the switch with the
same sentence (
chat.isAgentOff,agentOffText,checkAgain(),isInputEnabled). The grants view showsgrants.agentOffGrantsText: the grants have ended. React and Vue, five languages (the console's own words in each). - Provenance: a module that asks the server itself goes through
ctx.route(call), so its calls join the switch too.
Testing¶
FakeGateway has turnOff() and turnOn() (.NET: the SDK's own test gateway's TurnOff() and TurnOn()): every agent route but the
profile, the events and the manifest answers the 403, the profile says enabled: false, and the grants end with revoked_by:
agent_turned_off. refusedWhileOff(from) lists the requests that went to a refused route.