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 on the device.
Stop everything¶
agent.StopAllAsync() (TypeScript: agent.stopAll()) is the emergency stop:
- Every running turn in every open chat of the agent stops the way the chat's own Stop button does. The turn ends as
stopped (its stream throws
OperationCanceledException, 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:ChatSession.Stop()(TypeScript:chat.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;
ResetApprovalsAsyncforgets it.
The part on the device 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 on the device 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.
StopAllAsync 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 is true when the
stop found nothing to stop. For an app with several agents, FadenstackAgent.StopAllAsync(agents) (TypeScript:
stopAll(agents)) stops them all on the device first and then tells the servers; the result is the sum.
The control for the tray or the title bar¶
StopEverythingViewModel (Fadenstack.UI.Settings; TypeScript StopEverythingViewModel) takes the agents as a function,
because they come and go, and has StopCommand, 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. Each skin has StopEverythingButton: an icon button named "Stop everything" with a tooltip, and
the result line, in en, de, fr, es and zh-Hans. Host it where the person finds it quickly.
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 FadenstackSignInRequiredException (TypeScript: FadenstackSignInRequiredError), 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,FadenstackApiException.IsAgentDisabled(TypeScript:errorCodes.agentDisabled,isAgentDisabled(error));AgentProfile.Enabled(enabled; true when the key is missing, as from an older server);ChatOutcome.AgentDisabled("agent_disabled"). - Agent:
agent.TurnedOff(turnedOff) with the eventTurnedOffChanged(onTurnedOffChange(listener)). 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
AgentDisabledand the sentence above as its notice; - nothing retries: no further request goes to any agent route (they fail on the device 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, and
DELETEof a grant is not needed (the server ended them); - someone the agent does not let in still gets
agent_not_grantedoragent_retired, as before. - Try again:
agent.CheckAgainAsync()(checkAgain()) 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 (
AgentChatViewModel.IsAgentOff,AgentOffText,CheckAgainCommand,IsInputEnabled). The grants view showsAgentOffGrantsText: the grants have ended. All four skins, five languages (the console's own words in each).
Testing¶
To test the off-switch, answer as the server does. The TypeScript SDK's test gateway has fakeGateway.turnOff() and turnOn() (@fadenstack/testing) for it; in .NET, make your own fake server do the same. 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.