AI_IDE_Support.ns

Newspeak3
'Root'
class AI_IDE_Support usingPlatform: platform ide: webIde = Object new (
	(* IDE module providing AI integration. Sources AIAccess from the platform
 and the chat UI classes from Hopscotch (where they now live as
 top-level siblings, no longer a separate AIChatUI module). Defines
 IDE-specific tools that allow an AI model to query the IDE via mirrors.

 This module follows the standard IDE module pattern: it is parameterized
 by the platform and the IDE, and is instantiated by HopscotchWebIDE.

 Other IDE presenters can access AI functionality through this module,
 e.g., to embed a ChatSubject in a method or class presenter. *)
	
	(* IDE dependencies *)
	
	|
		private Root = webIde namespacing Root.
		private systemScope = webIde namespacing systemScope.
		private ClassMirror = platform mirrors ClassMirror.
		private ObjectMirror = platform mirrors ObjectMirror.
		private ActivationMirror = platform mirrors ActivationMirror.
		private ClassDeclarationBuilder = platform mirrors ClassDeclarationBuilder.
		private List = platform collections List.
		private Map = platform collections Map.
		private Set = platform collections Set.
		private ide = webIde.
		private js = platform js.
		private JSString = platform js global at: 'String'.
		private Document = webIde documents Document.
		private Presenter = platform hopscotch Presenter.
		private FileChooserFragment = platform hopscotch FileChooserFragment.
		private HTMLFragment = platform hopscotch HTMLFragment.
		
		(* AI capability comes from the platform: aiAccess is the non-UI
	   service module, aiColors is the chat-bubble palette grouped on
	   Hopscotch. *)
		public aiAccess = platform hopscotch aiAccess.
		private aiColors = platform hopscotch aiColors.
		
		(* Re-export commonly needed classes for use by other IDE modules *)
		public Tool = aiAccess Tool.
		public Provider = aiAccess Provider.
		public AnthropicProvider = aiAccess AnthropicProvider.
		public GeminiProvider = aiAccess GeminiProvider.
		public OpenAICompatibleProvider = aiAccess OpenAICompatibleProvider.
		public Session = aiAccess Session.
		private AIChatSetupSubject = platform hopscotch AIChatSetupSubject.
		private AIChatSetupPresenter = platform hopscotch AIChatSetupPresenter.
		private BaseChatSubject = platform hopscotch ChatSubject.
		private BaseChatPresenter = platform hopscotch ChatPresenter.
		private ChatStatusPresenter = platform hopscotch ChatStatusPresenter.
		private ChatInputPresenter = platform hopscotch ChatInputPresenter.
		
		(* --- AI focus state ---

	   Brain buttons in the IDE install a focus describing what the user is
	   currently asking the chat about. Three orthogonal pieces of state:

	   1. currentFocusBlock — a [ ^String ] block producing a description on
	      demand. Returned by the current_focus tool. A block (not a snapshot)
	      lets the description reflect live state — e.g. an in-progress
	      unaccepted edit, post-replacement updated source.

	   2. currentFocusValidator — a [ ^Boolean ] block that checks whether the
	      focused entity still exists. Run on every current_focus call. Returns
	      false (or raises) → focus is cleared. This catches all paths by which
	      an entity can disappear (explicit delete, add_or_replace_nested_class,
	      etc.) without each path needing to know about the focus.

	   3. focusKind / focusClassPath / focusSide / focusSelector — structured
	      identity used by isFocusedOnX:... matchers. Brain-button highlighting
	      compares against this rather than the Subject that installed the
	      focus. Reason: atomic install only forwards mixin objects, not
	      individual methods, so MethodMirror equality fails after a replace,
	      MirrorGroupSubject>>updateElements creates a fresh MethodSubject,
	      and any Subject-object-identity check fails. Structural matching
	      survives that. *)
		currentFocusBlock
		currentFocusValidator
		
		(* focusKind: #class | #classHeader | #method | #lazySlot | #evaluator | nil *)
		focusKind
		
		(* focusClassPath: String, dotted path *)
		focusClassPath
		
		(* focusSide: 'instance' | 'class' | nil *)
		focusSide
		
		(* focusSelector: Symbol — method or lazy-slot name, or nil *)
		focusSelector
		
		(* focusSha_slot: String (full git oid) — present only when the focus is
	   on a historical version of a member (i.e. installed via
	   setHistoryFocusOnEntry:). Nil otherwise. The isFocusedOnHistory:sha:
	   predicate and the read-tool fan-out branch on this. *)
		focusSha_slot
		
		(* focusHistoricalSource_slot: String — the version's source, captured
	   at focus install time. Returned by get_member_source /
	   get_class_header when the request matches the historical focus. Set
	   together with focusSha_slot. *)
		focusHistoricalSource_slot
		
		(* focusEvaluatorMirror_slot: ObjectMirror | ActivationMirror — set when
	   focusKind = #evaluator. Used directly as the identity for matcher
	   comparison; also exposed via the 'focus' object-registry id so
	   evaluate(in_id: 'focus') routes to the focused evaluator's receiver. *)
		focusEvaluatorMirror_slot
		
		(* focusEvaluatorSubject_slot: the EvaluatorSubject (or subclass) that
	   installed the focus. We retain it so 'focus' evaluations can append
	   results to its evaluator's results list, making them visible in the
	   IDE evaluator pane just like the workspace case. *)
		focusEvaluatorSubject_slot
		
		(* The chat the brain button / inline region / toolbar currently *target*
	   — NOT "the only one". Multiple chat docs coexist live, each with its own
	   subject on its own `chatSubjectSlot`; this slot only records which one is
	   the current target. It moves only on deliberate selection (makeCurrentChat:,
	   the switcher) or new-chat creation (startChat) — never on render — so
	   rendering/transcluding other chat docs never steals the target (M1). *)
		currentChatSubject_slot
		
		(* AI-proposed code changes staged for atomic install. Keyed by
	   changeset id (e.g. "cs1"); the value is a List of change records
	   (Maps with kind, class_name, side, and either source or selector
	   plus old_source). Cleared on apply or discard. *)
		proposedChangesets = Map new.
		nextChangesetIdNum ::= 0.
		
		(* AI object registry — Map[String, ObjectMirror] of objects the AI
	   can refer to by id. Pre-populated with the AI workspace under id
	   'workspace' the first time it is reached. Subsequent entries come
	   from evaluate's non-primitive results, each auto-named (r1, r2, ...)
	   or AI-named via the name: parameter. Debugger activations get
	   their own ids (a1, a2, ...). Deliberately NOT cleared on chat-clear:
	   results reachable here may not be reachable from the workspace's
	   result list (e.g. when the AI navigates and evaluates transitively
	   through results). *)
		objectRegistry = Map new.
		nextResultIdNum ::= 0.
		nextActivationIdNum ::= 0.
		
		(* Cached AI workspace ObjectSubject. We keep the Subject (not just
	   the mirror) so workspace evaluations can be routed through the
	   subject's EvaluatorSubject — its evaluate: appends the resulting
	   ThreadMirror to the workspace's results list, which is what the
	   workspace presenter renders. Without this, the AI workspace UI
	   stays blank no matter how many evaluations run. *)
		aiWorkspaceSubject_slot
		
		(* Map[String, TestingInProgressSubject] keyed by test configuration
	   class simpleName. Captured by run_tests so subsequent
	   get_test_results / run_failing_tests / run_erroring_tests / run_test
	   tools can read and mutate the same Tester. Selective re-runs
	   operate on this cached Tester in place; a fresh run_tests
	   overwrites the entry. *)
		testersByConfigName = Map new.
		
		(* The chatHolder currently displaying the shared AI chat, paired
	   with the page subject it sits on. The brain-click path closes the
	   previous chat region ONLY when the new click is on the same page;
	   if the user navigates A → click → B → click → back to A, A's chat
	   region stays as the user left it. Set together via
	   activeChatHolder:page:. *)
		activeChatHolder_slot
		activeChatHolderPage_slot
	|
) (
	public class IDEChatSetupSubject onModel: providerClass <Class> = AIChatSetupSubject onModel: providerClass (
		(* IDE-specific chat setup. Adds providerName + docName fields. startChat is
 overridden: instead of constructing an in-memory ChatSubject, it persists
 the API key (under the per-provider storage key derived from providerName),
 creates a ChatDocument in Root with the configured provider + model, makes
 that doc the active chat doc (in localStorage), caches its chat subject
 as the shared session for ephemeral brain-button chats, and returns a
 DocumentSubject for navigation so the user lands on the new doc.

 storageKey is overridden so it derives from providerName rather than from
 the onModel: providerClass — letting one setup subject manage keys for
 every supported provider as the user toggles the dropdown. *)
		
		|
			public docName <String>
			public providerName <String> ::= 'anthropic'.
			public baseUrl <String> ::= ''.
		|
		
		(* The parent's initializer already tried to load apiKey via storageKey,
	   but our overridden storageKey reads providerName which wasn't yet
	   initialized — the parent's on:Error swallowed and left apiKey empty.
	   Reload now that providerName is set. *)
		reloadApiKey.
		reloadBaseUrl.
		docName:: defaultDocNameForProvider: providerName.
	) (
		storageKey ^<String> = (
			^'ns_ai_apikey_' , (providerClassFor: providerName) name
		)
		public reloadBaseUrl = (
			(* Refresh baseUrl from localStorage (or fall back to the provider's
	   default). Called from the initializer and on every provider
	   switch so the form reflects the current provider's URL config. *)
			
			baseUrl:: baseUrlForProvider: providerName
		)
		public createProvider = (
			(* Override the base AIChatSetupSubject>>createProvider to dispatch
	   on providerName: openai-compat needs the 3-arg factory carrying
	   baseUrl; others use the inherited 2-arg shape. The base impl
	   reads `model` which is the original onModel: providerClass and
	   never updates on dropdown switch, so we explicitly resolve via
	   providerClass (which itself routes through providerClassFor:). *)
			
			| klass |
			klass:: providerClass.
			providerName = 'openai-compat' ifTrue: [
					^klass apiKey: apiKey model: modelName baseUrl: baseUrl
				].
			^klass apiKey: apiKey model: modelName
		)
		public providerClass = (
			(* Override the base AIChatSetupSubject's `model`-based providerClass
	   so the live provider class always tracks the dropdown's
	   providerName. The base subject stores the class in `model` and
	   never updates it; in the IDE flow the dropdown only mutates
	   providerName, so we resolve via providerClassFor: every access.
	   Lets the base AIChatSetupPresenter modelField (which reads
	   subject providerClass) work without an IDE-specific override. *)
			
			^providerClassFor: providerName
		)
		public reloadApiKey = (
			| key <String | UndefinedObject> |
			key:: [ js localStorage getItem: storageKey ] on: Exception do: [:e | nil ].
			key isNil ifTrue: [ key:: '' ].
			apiKey:: key
		)
		public createSession: provider <Provider> ^<Session> = (
			| session <Session> |
			session:: Session provider: provider tools: (toolsForProvider: provider).
			session systemPrompt: newspeakSystemPrompt.
			^session
		)
		public createPresenter = (
			^IDEChatSetupPresenter onSubject: self
		)
		public defaultDocNameForProvider: pname <String> ^<String> = (
			(* Generate a default chat document name for the given provider that
	   doesn't clash with any existing Root entry. Pattern is
	   <ProviderLabel>Chat for the first one, then <ProviderLabel>Chat2,
	   <ProviderLabel>Chat3, and so on. Called at construction time to
	   seed the docName slot, and again on provider switch to keep the
	   default in sync with the chosen provider. *)
			
			| base candidate n |
			base:: (providerDisplayLabelFor: pname) , 'Chat'.
			(Root includesKey: base asSymbol) ifFalse: [ ^base ].
			n:: 2.
			[
				candidate:: base , n printString.
				(Root includesKey: candidate asSymbol) ifFalse: [ ^candidate ].
				n:: n + 1
			] repeat
		)
		providerDisplayLabelFor: pname <String> ^<String> = (
			(* Title-case label used to seed the default chat doc name. New
	   providers should add a case here as they land; unknown keys fall
	   back to the key itself. *)
			
			pname = 'anthropic' ifTrue: [ ^'Anthropic' ].
			pname = 'gemini' ifTrue: [ ^'Gemini' ].
			pname = 'openai-compat' ifTrue: [ ^'Local' ].
			^pname
		)
		public startChat = (
			(* Persist key, create the ChatDocument in Root under docName, install
	   it as the active chat doc (localStorage + currentChatSubject_slot),
	   and return a DocumentSubject so navigation lands on the new doc.
	   Returns nil on validation failure with errorMessage set. *)
			
			| doc <Document> |
			apiKey isEmpty ifTrue: [
					errorMessage:: 'Please enter an API key.'.
					^nil
				].
			docName isEmpty ifTrue: [
					errorMessage:: 'Please enter a chat name.'.
					^nil
				].
			(Root includesKey: docName asSymbol) ifTrue: [
					errorMessage:: 'An entry named "' , docName , '" already exists in Root.'.
					^nil
				].
			[ js localStorage setItem: storageKey to: apiKey ] on: Exception do: [:e | ].
			providerName = 'openai-compat' ifTrue: [
					[
						js localStorage setItem: (baseUrlStorageKeyFor: providerName) to: baseUrl
					] on: Exception do: [:e | ]
				].
			[ js localStorage setItem: 'ns_ai_active_chat_doc' to: docName ] on: Exception
				do: [:e | ].
			doc:: createChatNamed: docName provider: providerName model: modelName.
			Root at: docName asSymbol put: doc.
			currentChatSubject_slot:: doc chatSubject.
			ide browsing updateCurrentDisplay.
			^ide documents DocumentSubject onModel: doc
		)
		public newChatSubjectFor: session <Session> ^<IDEChatSubject> = (
			(* Legacy path: not used now that startChat creates a ChatDocument and
	   caches its chatSubject directly. Kept as a defensive fallback if any
	   caller bypasses startChat. *)
			
			| chat <IDEChatSubject> |
			chat:: IDEChatSubject onModel: session.
			currentChatSubject_slot:: chat.
			^chat
		)
		public isKindOfIDEChatSetupSubject ^<Boolean> = (
			^true
		)
		isMyKind: other ^<Boolean> = (
			^other isKindOfIDEChatSetupSubject
		)
	) : ()
	public class ChatFocus onDoc: doc <Document | UndefinedObject> = Object new (
		(* Per-chat brain-button focus (M2a). Each chat (session) owns one; the
	   current_focus tool built for that session reads THIS focus, so concurrent
	   sessions never share focus. docLabel names the host chat document and is
	   constant for the chat; block/validator are the brain-button snapshot,
	   captured by captureFocusInto: when a brain opens/targets this chat. *)

		|
			block
			validator
			chatDoc_slot = doc.
			docLabel = doc isNil ifTrue: [ '' ] ifFalse: [ 'Active chat document: ' , doc name , '. ' ].
		|
	) (
		public chatDoc ^<Document | UndefinedObject> = (
			(* The chat document this focus/session belongs to (nil for doc-less
		   sessions). Lets a per-session tool route to ITS chat — e.g. propose_changes
		   enqueues the changeset onto the proposing chat, not the global current (M2b). *)
			^chatDoc_slot
		)
		public installBlock: b validator: v = (
			block:: b.
			validator:: v
		)
		public clear = (
			block:: nil.
			validator:: nil
		)
		public description ^<String> = (
			^docLabel , focusPart
		)
		focusPart ^<String> = (
			(* Mirrors the old module-global computeFocusOnly: validate the focused
		   entity still exists, then render; drop a stale focus. *)
			block isNil ifTrue: [ ^'(no focus set)' ].
			validator isNil ifFalse: [
					([ validator value ] on: Error do: [:e | false ]) ifFalse: [
							clear.
							^'(no focus set)'
						]
				].
			^[ block value ] on: Error
				do: [:e | '(focus block raised: ' , e messageText , ')' ]
		)
	) : ()
	public class IDEChatSubject onModel: session <Session> = BaseChatSubject onModel: session (
		(* IDE-aware chat subject; returns an IDE presenter so Inspect Presenter works.

 Also carries the inline-chat side of the changeset-attachment machinery:
   pendingChangesetIds          ids staged by propose_changes during the
                                in-flight turn, drained by markComplete
                                onto the last assistant message index.
   changesetIdsByMessageIndex   Map[Integer, List[String]] — which
                                proposals belong to which assistant
                                message in displayMessages.
   changesetSubjectsById        per-id ChangesetSubject cache so the
                                presenter survives across renders without
                                hitting the runaway-compute bug.

 IDEChatDocumentSubject inherits these slots but uses ChatDocument's
 own pendingChangesetIds / appendChangesetAmpletFor: pipeline; the
 inherited fields stay empty in that flow. *)
		
		|
			public pendingChangesetIds <List[String]> ::= List new.
			public changesetIdsByMessageIndex <Map[Integer, List[String]]> ::= Map new.
			public changesetSubjectsById <Map[String, Object]> ::= Map new.
		|
	) (
		public createPresenter = (
			^IDEChatPresenter onSubject: self
		)
		public isKindOfIDEChatSubject ^<Boolean> = (
			^true
		)
		isMyKind: other ^<Boolean> = (
			^other isKindOfIDEChatSubject
		)
		public attachedChangesetIdsAt: messageIndex <Integer> ^<List[String]> = (
			^changesetIdsByMessageIndex at: messageIndex ifAbsent: [ List new ]
		)
		public forgetCachedChangesetSubjectFor: id <String> = (
			changesetSubjectsById removeKey: id ifAbsent: [ ]
		)
		public changesetSubjectFor: id <String> ^<Object | UndefinedObject> = (
			(* Pure model accessor: return the cached ChangesetSubject for
	   this proposal id, building it on first use, or nil if the
	   underlying records are gone (applied / discarded / never
	   staged). The caller (IDEChatPresenter>>messagesArea) wraps a
	   non-nil result in a ChangesetPresenter and renders a
	   "no longer pending" label for the nil case — presentation
	   stays on the presenter side.

	   Caching is required: prepareForLiveViewRefresh: nukes the
	   Ampleforth fragment cache on every refresh and the inline
	   presenter rebuilds messagesArea on every uiGeneration bump,
	   so without a stable subject the first render's synchronous
	   compute would fire refreshBlock → updateGUI → another render
	   → fresh subject → ... runaway. *)
			
			| records |
			records:: proposedChangesets at: id ifAbsent: [ nil ].
			records isNil ifTrue: [
					changesetSubjectsById removeKey: id ifAbsent: [ ].
					^nil
				].
			^changesetSubjectsById at: id
				ifAbsent: [
					| strategy s subj |
					subj:: self.
					strategy:: AIInstallStrategy onRecords: records
						changesetId: id
						onApplied: [:csId <String> :recCount <Integer> |
							(* M3: notify other open chats that the codebase changed. *)
							broadcastChangeAppliedBy: subj records: records
						]
						onCanceled: [
							subj forgetCachedChangesetSubjectFor: id.
							ide browsing updateCurrentDisplay
						]
						onComputed: [ ].
					s:: ChangesetSubject onModel: strategy.
					s autoExpand: true.
					changesetSubjectsById at: id put: s.
					s
				]
		)
		public markComplete = (
			(* Drain pendingChangesetIds onto the last assistant message
	   index, so the inline ChatPresenter's messagesArea can render
	   a ChangesetPresenter inline under that turn. For doc-backed
	   subjects the same ids are *also* queued on the chat doc
	   (enqueuePendingChangesetId: pushes to both queues), so the
	   doc's amplet pipeline keeps working in parallel. *)
			
			super markComplete.
			pendingChangesetIds isEmpty ifFalse: [
					| lastIdx bucket fresh |
					lastIdx:: self lastAssistantMessageIndex.
					lastIdx isNil ifFalse: [
							bucket:: changesetIdsByMessageIndex at: lastIdx
								ifAbsent: [
									| b |
									b:: List new.
									changesetIdsByMessageIndex at: lastIdx put: b.
									b
								].
							pendingChangesetIds do: [:id | bucket add: id ]
						].
					
					(* Clear pending — replace with a fresh List rather than
		   removeAll, since List's API for in-place truncation varies
		   across runtimes. *)
					fresh:: List new.
					pendingChangesetIds:: fresh
				]
		)
		lastAssistantMessageIndex ^<Integer | UndefinedObject> = (
			| msgs i |
			msgs:: session displayMessages.
			i:: msgs size.
			[ i > 0 ] whileTrue: [
					((msgs at: i) at: 1) = 'assistant' ifTrue: [ ^i ].
					i:: i - 1
				].
			^nil
		)
		public clearHistory = (
			super clearHistory.
			changesetIdsByMessageIndex:: Map new.
			changesetSubjectsById:: Map new.
			pendingChangesetIds:: List new
		)
	) : ()
	public class IDEChatSetupPresenter onSubject: s <IDEChatSetupSubject> = AIChatSetupPresenter onSubject: s (
		(* IDE-flavoured setup presenter. Adds a provider dropdown, a chat-name
 field (the Root entry the ChatDocument will be created under), and
 overrides Inspect Presenter to route through the IDE's namespacing. *)
		
		|
			docNameEditor
			baseUrlEditor
		|
	) (
		definition = (
			| rows |
			rows:: List new.
			rows add: helpSection.
			rows add: (row: {(label: 'AI Chat Setup') bold. filler. helpButton. dropDownMenu: [
							actionsMenu
						]. }).
			rows add: mediumBlank.
			rows add: (label: 'Configure your AI provider and chat document. API keys are stored per provider in your browser''s localStorage; the chat document lives in your IDE namespace.').
			rows add: mediumBlank.
			rows add: (row: {(label: 'Provider: ') bold. smallBlank. providerPicker. }).
			rows add: mediumBlank.
			subject providerName = 'openai-compat' ifTrue: [
					rows add: (row: {(label: 'Base URL: ') bold. elastic: baseUrlField. }).
					rows add: (label: 'Local servers must allow CORS for this origin — e.g. for Ollama set OLLAMA_ORIGINS=* before launching.') italic.
					rows add: mediumBlank
				].
			rows add: (row: {(label: 'API Key: ') bold. elastic: apiKeyField. }).
			rows add: mediumBlank.
			rows add: (row: {(label: 'Model: ') bold. elastic: modelField. }).
			rows add: mediumBlank.
			rows add: (row: {(label: 'Chat name: ') bold. elastic: docNameField. }).
			rows add: mediumBlank.
			rows add: errorArea.
			rows add: (row: {filler. button: 'Start Chat' action: [ respondToStart ]. }).
			^column: rows
		)
		baseUrlField = (
			(* CodeMirror text editor bound to subject baseUrl. Only rendered
	   when providerName = 'openai-compat'. The acceptResponse mirrors
	   apiKeyField's pattern: pressing Enter commits the typed URL AND
	   triggers updateGUI: so modelField re-evaluates against the new
	   URL's cache (which usually misses, surfacing the freeform field
	   for a never-tried URL). *)
			
			baseUrlEditor:: codeMirror: subject baseUrl.
			baseUrlEditor changeResponse: [:frag |
					subject baseUrl: frag textBeingAccepted
				].
			baseUrlEditor acceptResponse: [:frag |
					
					(* leaveEditState must run BEFORE updateGUI: so the next render
		   sees the editor already out of edit state — otherwise the JS
		   visual keeps the green/red Accept/Cancel buttons visible.
		   Same idiom as ChatInputPresenter>>respondToSend. *)
					subject baseUrl: frag textBeingAccepted.
					frag leaveEditState.
					updateGUI: [ ]
				].
			^baseUrlEditor
		)
		providerPicker = (
			(* Provider selector. Picking a provider swaps in its default model
	   name, reloads the stored API key for it, and resyncs the visible
	   form state — see respondToProviderSwitch:defaultModel: for why
	   the resync is non-trivial. *)
			
			^row: {(label: subject providerName) bold. smallBlank. dropDownMenu: [
						menuWithLabelsAndActions: {{'Anthropic'. [
								respondToProviderSwitch: 'anthropic' defaultModel: 'claude-sonnet-4-6'
							]. }. {'Gemini'. [
								respondToProviderSwitch: 'gemini' defaultModel: 'gemini-3.5-flash'
							]. }. {'Local (OpenAI-compatible)'. [
								respondToProviderSwitch: 'openai-compat' defaultModel: ''
							]. }. }
					]. }
		)
		respondToProviderSwitch: providerName <String> defaultModel: defaultModel <String> = (
			(* Switch provider and resync the visible form so the API-key
	   editor, model editor, and toggle expansion all reflect the
	   newly-chosen provider rather than the previous one.

	   Plain updateGUI: alone isn't enough: ToggleComposer's
	   updateVisualsFromSameKind: preserves the old isExpanded across
	   re-renders, and CodeMirrorFragment's preserves the old editor's
	   text. We explicitly mutate the existing presenter slots
	   (keyToggle, keyEditor, modelEditor, keyRevealed) so the diff
	   inherits the new state on re-render. *)
			
			updateGUI: [
					subject providerName: providerName.
					subject modelName: defaultModel.
					subject docName: (subject defaultDocNameForProvider: providerName).
					subject reloadApiKey.
					subject reloadBaseUrl.
					keyRevealed:: subject apiKey isEmpty.
					keyToggle isNil ifFalse: [
							keyRevealed ifTrue: [ keyToggle expand ] ifFalse: [ keyToggle collapse ]
						].
					keyEditor isNil ifFalse: [ keyEditor text: subject apiKey ].
					modelEditor isNil ifFalse: [ modelEditor text: subject modelName ].
					docNameEditor isNil ifFalse: [ docNameEditor text: subject docName ].
					baseUrlEditor isNil ifFalse: [ baseUrlEditor text: subject baseUrl ]
				]
		)
		docNameField = (
			docNameEditor:: codeMirror: subject docName.
			docNameEditor changeResponse: [:frag |
					subject docName: frag textBeingAccepted
				].
			^docNameEditor
		)
		respondToStart = (
			subject docName: docNameEditor textBeingAccepted.
			super respondToStart
		)
		respondToInspectPresenter = (
			enterSubject: (ide browsing ObjectSubject onModel: (ObjectMirror reflecting: self))
		)
		public isKindOfIDEChatSetupPresenter ^<Boolean> = (
			^true
		)
		isMyKind: other ^<Boolean> = (
			^other isKindOfIDEChatSetupPresenter
		)
	) : ()
	public class IDEChatPresenter onSubject: s <IDEChatSubject> = BaseChatPresenter onSubject: s (
		(* Inline (non-document) chat presenter. Used for embedded chats (brain
 button → ephemeral region under the current page). ChatDocument-backed
 chats render through DocumentPresenter instead.

 onSwitchHandler: optional [:Document] block. When set (by a brain region that
 embeds this presenter), the chat switcher retargets THAT region's chat locally
 instead of moving the global current — so switching one brain region does not
 switch every other one. Re-injected on each region render, so it need not
 survive this presenter's own regeneration. *)

		| onSwitchHandler_slot |
	) (
		public onSwitchHandler: aBlock <[:Document]> = (
			onSwitchHandler_slot:: aBlock
		)
		respondToInspectPresenter = (
			enterSubject: (ide browsing ObjectSubject onModel: (ObjectMirror reflecting: self))
		)
		public isKindOfIDEChatPresenter ^<Boolean> = (
			^true
		)
		isMyKind: other ^<Boolean> = (
			^other isKindOfIDEChatPresenter
		)
		messagesArea = (
			(* Override of BaseChatPresenter>>messagesArea that interleaves
	   ChangesetPresenters under any assistant message they were
	   attached to (via subject changesetIdsByMessageIndex, populated
	   by IDEChatSubject>>markComplete from propose_changes calls
	   made during the turn). The base method renders only the
	   {role, text} pairs; we keep its messageFragment: for the row
	   itself and add a ChangesetPresenter as a sibling in the column
	   for each attached id whose proposal is still pending. When the
	   proposal has been applied or discarded, subject returns nil and
	   we render a small italic banner instead — keeping presentation
	   concerns out of the subject. *)
			
			| fragments msgs i |
			fragments:: List new.
			msgs:: subject messages.
			i:: 1.
			[ i <= msgs size ] whileTrue: [
					| attachedIds |
					fragments add: (messageFragment: (msgs at: i)).
					attachedIds:: subject attachedChangesetIdsAt: i.
					attachedIds do: [:csId |
							| cs |
							cs:: subject changesetSubjectFor: csId.
							fragments add: smallBlank.
							fragments add: (cs isNil ifTrue: [
										(label: 'Changeset ' , csId , ' is no longer pending.') italic
									]
									ifFalse: [ ChangesetPresenter onSubject: cs ])
						].
					fragments add: smallBlank.
					i:: i + 1
				].
			subject errorMessage isNil ifFalse: [
					fragments add: ((label: 'Error: ' , subject errorMessage) color: aiColors errorText)
				].
			fragments isEmpty ifTrue: [
					fragments add: (label: 'Send a message to start a conversation.') italic
				].
			^column: fragments
		)
		headingBar = (
			(* Override BaseChatPresenter>>headingBar to add a New-chat button and a
	   chat switcher, so a new chat (optionally with a different provider or
	   model) can be started and any existing chat selected directly from a
	   regular chat presenter — not only from a ChatDocument's chatControls.
	   The Clear / help / actions affordances from the base bar are kept. *)
			
			^row: {(label: 'Chat') bold. filler. button: 'New Chat'
					action: [ openNewChatSetup ]. smallBlank. chatSwitcher. smallBlank. button: 'Clear'
					action: [ updateGUI: [ subject clearHistory ] ]. helpButton. dropDownMenu: [
						actionsMenu
					]. }
		)
		chatSwitcher = (
			(* Dropdown of every ChatDocument in Root. Selecting one switches THIS
	   chat region in place to that chat — it does NOT navigate to the chat's
	   document view. The inline region always renders ensureSharedChat, so
	   making the selected chat current and refreshing re-renders this region
	   on its conversation. The previously shown chat keeps its Session, so
	   reselecting it resumes its history. *)
			
			^row: {label: 'Chats:'. smallBlank. dropDownMenu: [
						menuWithLabelsAndActions: (chatDocumentsInRoot collect: [:doc |
									{doc name. [ respondToSwitchToChat: doc ]. }
								])
					]. }
		)
		respondToSwitchToChat: doc <Document> = (
			(* Switch this chat region to `doc`. If embedded in a brain region
	   (onSwitchHandler set), retarget only THAT region's chat — local, no effect
	   on other regions or the global current. Otherwise (standalone) fall back to
	   moving the global current and refreshing this presenter, as before. No
	   navigation either way — the user stays on the current page. *)

			onSwitchHandler_slot isNil
				ifFalse: [ ^onSwitchHandler_slot value: doc ].
			makeCurrentChat: doc.
			updateGUI: [ ]
		)
	) : ()
	public class ChatControlsPresenter onSubject: doc <Document> = Presenter onSubject: doc (
		(* Renders a chat document's control row (New Chat + chat switcher). Lives in
 AI_IDE_Support so the rendering is single-sourced across every chat document;
 a chat doc's `chatControls` amplet just forwards here (^ide aiSupport
 chatControlsFor: self). Selecting a chat navigates to that chat's document
 view — under the clone-template design each chat IS its own document, so
 switching = showing that document. *)
		
	) (
		definition = (
			^row: {button: 'New Chat' action: [ openNewChatSetup ]. mediumBlank. label: 'Chats:'. smallBlank. dropDownMenu: [
						menuWithLabelsAndActions: chatSwitchMenuActions
					]. filler. }
		)
		public isKindOfChatControlsPresenter ^<Boolean> = (
			^true
		)
		isMyKind: other ^<Boolean> = (
			^other isKindOfChatControlsPresenter
		)
	) : ()
	public class IDEChatDocumentSubject onChatDocument: doc <Document> session: s <Session> focus: f <ChatFocus> = IDEChatSubject onModel: s (
		(* Chat subject bound to a ChatDocument: instead of (or in addition to)
 the conversation living in the inline ChatPresenter view, each turn is
 appended as an HTML section into the document's contents and the live
 view is refreshed. The Session under the hood is still the source of
 truth for messages — the document sections are a *projection* of what
 displayMessages returns. We track lastTurnIndexBeforeSend so that, on
 markComplete, we only render the assistant turns that arrived during
 this round-trip rather than re-rendering history. *)
		
		|
			public document <Document> = doc.
			lastTurnIndexBeforeSend <Integer>
			chatFocus_slot <ChatFocus> = f.
		|
	) (
		public isKindOfIDEChatDocumentSubject ^<Boolean> = (
			^true
		)
		public focus ^<ChatFocus> = (
			(* This chat's per-session brain-button focus (M2a). Read by its
		   current_focus tool; written by captureFocusInto: on a brain click. *)
			^chatFocus_slot
		)
		public sendText: text <String> ^<Alien[Promise] | UndefinedObject> = (
			| promise <Alien[Promise] | UndefinedObject> |
			text isEmpty ifTrue: [ ^nil ].
			document appendUserSection: text.
			lastTurnIndexBeforeSend:: session displayMessages size.
			
			(* super sendText: flips the chat subject's waiting flag, but it does
	   so AFTER our appendUserSection: above has already published. So we
	   re-publish here via a no-op mutation so the live view picks up the
	   thinking indicator alongside the user section. *)
			promise:: super sendText: text.
			document mutateContentsTo: document contents.
			^promise
		)
		appendNewAssistantTurnsAfter: startIdx <Integer> = (
			(* Render only the assistant turns added since startIdx. Tool-use
	   rounds can produce multiple assistant messages per send (one per
	   model→tool→model cycle); we want each as its own bubble. *)
			
			| msgs <List> i <Integer> |
			msgs:: session displayMessages.
			i:: startIdx + 1.
			[ i <= msgs size ] whileTrue: [
					| msg <Array> role <String> text <String> |
					msg:: msgs at: i.
					role:: msg at: 1.
					text:: msg at: 2.
					role = 'assistant' ifTrue: [ document appendAssistantSection: text ].
					i:: i + 1
				]
		)
		public markComplete = (
			super markComplete.
			appendNewAssistantTurnsAfter: lastTurnIndexBeforeSend.
			
			(* Drain any changeset ids proposed during this turn. Each id
	   becomes a ChangesetPresenter amplet appended after the last
	   assistant section, inline with the conversation transcript. *)
			[ document pendingChangesetIds isEmpty ] whileFalse: [
					| id |
					id:: document pendingChangesetIds removeFirst.
					document appendChangesetAmpletFor: id
				].
			
			(* super flipped waiting back to false. Re-publish so the thinking
	   indicator is replaced with the model picker. *)
			document mutateContentsTo: document contents.
			ide browsing updateCurrentDisplay
		)
		public markError: msg <String> = (
			super markError: msg.
			document appendErrorSection: msg.
			ide browsing updateCurrentDisplay
		)
		public sendText: text <String> attachments: docs <List> ^<Alien[Promise] | UndefinedObject> = (
			(* Like sendText: but forwards document attachments down the chain.
	   docs is a List of { filename <String>. content <String> } tuples.
	   Mirrors the structure of sendText: exactly. *)
			
			| promise <Alien[Promise] | UndefinedObject> |
			text isEmpty ifTrue: [ ^nil ].
			document appendUserSection: text.
			lastTurnIndexBeforeSend:: session displayMessages size.
			promise:: super sendText: text attachments: docs.
			
			(* Re-publish via a no-op mutation so the live view picks up the
	   thinking indicator from the waiting flag super just set. *)
			document mutateContentsTo: document contents.
			^promise
		)
	) : ()
	public class AIInstallStrategy onRecords: recs <List> changesetId: csid <String> onApplied: appliedBlk <[:String :Integer | Object]> onCanceled: canceledBlk <[]> onComputed: computedBlk <[]> = ApplyStrategy new (
		(* Strategy used by ChangesetSubject in the AI chat flow. When the
 user clicks "Apply" on a ChangesetPresenter rendered from a
 proposed AI changeset, this strategy installs the underlying
 records via the atomic installer and removes the entry from
 proposedChangesets. Three caller-supplied blocks let the host
 (ChatDocument or inline IDEChatSubject) react:

   appliedBlock   fires after a successful install with
                  (changesetId, recordCount); host can post a
                  confirmation turn / banner.
   canceledBlock  fires when the user clicks Cancel; host forgets
                  any cached presenter and forces a refresh.
   computedBlock  fires after the synchronous compute simulates
                  the changeset and the presenter's refreshBlock
                  has been invoked. Doc-backed hosts use this to
                  fire contentsChanged on the chat doc — without
                  it, refreshBlock = updateGUI: only rebuilds
                  Hopscotch presenter substances and the doc's
                  live view (which observes contentsChanged) keeps
                  showing the cached "Computing changeset..." label
                  until the user manually refreshes. Inline hosts
                  pass an empty block because their presenter does
                  re-render on updateGUI:.

 Lexical access to the enclosing AI_IDE_Support module gives the
 strategy direct call sites for applyChangesetRecords:,
 proposedChangesets, and simulateRecordsAsChangeset:. *)
		
		|
			private records <List> = recs.
			private changesetId <String> = csid.
			private appliedBlock <[:String :Integer | Object]> = appliedBlk.
			private canceledBlock <[]> = canceledBlk.
			private computedBlock <[]> = computedBlk.
		|
	) (
		public actionLabel ^<String> = (
			^'Apply'
		)
		public requiresMessage ^<Boolean> = (
			^false
		)
		public liveNamespace = (
			^Root
		)
		public title ^<String> = (
			^'Apply changeset ' , changesetId
		)
		public requiresAuthor ^<Boolean> = (
			^false
		)
		public requiresApply ^<Boolean> = (
			^true
		)
		public validate: input <Map> onError: errBlock <[:String | Object]> ^<Boolean> = (
			^true
		)
		public onCancel = (
			(* Discard the proposal. Drop the staged records from
	   proposedChangesets, then let the caller forget any cached
	   presenter and force a host-side refresh so the amplet flips
	   to the "no longer pending" banner. *)
			
			proposedChangesets removeKey: changesetId ifAbsent: [ ].
			canceledBlock value
		)
		public apply: changeset <Map> withInput: input <Map> ^<Alien> = (
			(* Install the records, remove from proposedChangesets, fire the
	   appliedBlock for host-specific bookkeeping (e.g. doc-backed
	   chats append a confirmation turn; inline chats no-op and let
	   the post-submit banner inside the presenter speak for itself),
	   then resolve. Errors are caught and pushed through
	   Promise.reject — raising across the alien bridge would corrupt
	   the live view. *)
			
			| deferred resolveFn rejectFn |
			deferred:: aiAccess JSPromise withResolvers.
			resolveFn:: deferred at: 'resolve'.
			rejectFn:: deferred at: 'reject'.
			[
				applyChangesetRecords: records.
				proposedChangesets removeKey: changesetId ifAbsent: [ ].
				appliedBlock value: changesetId value: records size.
				resolveFn call: js undefined with: changesetId
			] on: Exception
				do: [:e |
					| msg |
					msg:: [ e messageText ] on: Exception do: [:e2 | nil ].
					msg isNil ifTrue: [ msg:: e printString ].
					rejectFn call: js undefined with: msg
				].
			^deferred at: 'promise'
		)
		public computeChangesetOnComplete: doneBlock <[:Map | Object]> onError: errBlock <[:String | Object]> = (
			(* Defer the synchronous compute via setTimeout(0). The
	   ChangesetSubject's computeAsync: hook delivers the result by
	   calling refreshBlock, which fires updateGUI: — bumping
	   uiGeneration and triggering a full re-render. If we ran
	   synchronously here we'd be inside the current render's
	   processChildren / currentFragment visual call, and the nested
	   re-render would re-enter that path, sometimes leaving the chat
	   doc with a half-rendered amplet (the model picker and input
	   editor amplets that follow this one silently fail to attach
	   their visuals). The repo strategies don't see this because
	   their git operations resolve asynchronously, so refreshBlock
	   only fires after the current frame unwinds; this setTimeout(0)
	   matches that timing for the pure-synchronous AI flow. *)
			
			js global setTimeout: [
					[
						doneBlock value: (simulateRecordsAsChangeset: records).
						computedBlock value
					] on: Exception
						do: [:e |
							| msg |
							msg:: [ e messageText ] on: Exception do: [:e2 | nil ].
							msg isNil ifTrue: [ msg:: e printString ].
							errBlock value: msg
						].
					nil
				]
				with: 0
		)
	) : ()
	lazy public repositories = ide repositories.
	lazy public ApplyStrategy = repositories ApplyStrategy.
	lazy public ChangesetSubject = repositories ChangesetSubject.
	lazy public ChangesetPresenter = repositories ChangesetPresenter.
	lazy public StaleChangesetPresenter = repositories StaleChangesetPresenter.
	lazy public StaleChangesetSubject = repositories StaleChangesetSubject.
	ensureModelMachineryGap: container <Object> beforeThinking: thinking <Object> ^<Object> = (
		(* Find the block-level gap that sits between the chat content and
	   the model machinery, creating one in-place if the doc was
	   built before initialChatDocumentContents: started emitting one.
	   Returned element is used as the insertion anchor by
	   insertTurnSection: and appendChangesetAmpletFor: so every new
	   row lands above the gap and the model picker / input editor
	   stay on their own line below it. *)
		
		| gaps gap jsDoc parent |
		gaps:: container getElementsByClassName: 'modelMachineryGap'.
		(gaps at: 'length') > 0 ifTrue: [ ^gaps at: 0 ].
		jsDoc:: js global at: 'document'.
		gap:: jsDoc createElement: 'div'.
		gap setAttribute: 'class' to: 'modelMachineryGap'.
		gap setAttribute: 'style'
			to: 'display:block; min-height:3em; padding:0.5em; margin:0.5em 0;'.
		
		(* No contenteditable override — inherits "true" from the
	   self_ampleforth wrapper so the user can type freeform notes
	   between AI responses and the model machinery. *)
		parent:: thinking at: 'parentNode'.
		parent insertBefore: gap before: thinking.
		^gap
	)
	findChatStructuralAmplet: name <String> in: container <Object> ^<Object | UndefinedObject> = (
		| amplets count i |
		amplets:: container getElementsByClassName: 'ampleforth'.
		count:: amplets at: 'length'.
		i:: 0.
		[ i < count ] whileTrue: [
				| amplet n |
				amplet:: amplets at: i.
				n:: amplet getAttribute: 'name'.
				n = name ifTrue: [ ^amplet ].
				i:: i + 1
			].
		^nil
	)
	providerClassFor: pn <String> = (
		pn = 'anthropic' ifTrue: [ ^AnthropicProvider ].
		pn = 'gemini' ifTrue: [ ^GeminiProvider ].
		pn = 'openai-compat' ifTrue: [ ^OpenAICompatibleProvider ].
		Error signal: 'Unknown provider: ' , pn , ' (supported: anthropic, gemini, openai-compat)'
	)
	apiKeyStorageKeyFor: pn <String> ^<String> = (
		^'ns_ai_apikey_' , (providerClassFor: pn) name
	)
	apiKeyForProviderOrNil: pn <String> ^<String | UndefinedObject> = (
		| key |
		[ key:: js localStorage getItem: (apiKeyStorageKeyFor: pn) ] on: Exception
			do: [:e | ^nil ].
		^key
	)
	apiKeyForProvider: pn <String> ^<String> = (
		| key |
		key:: apiKeyForProviderOrNil: pn.
		key isNil ifTrue: [
				Error signal: 'No API key stored for provider "' , pn , '". Set one via the chat setup screen first.'
			].
		^key
	)
	baseUrlStorageKeyFor: pn <String> ^<String> = (
		(* localStorage key for an OpenAI-compatible provider's base URL.
	   Only meaningful when pn = 'openai-compat'; harmless to compute
	   for other provider names but unused there. *)
		
		^'ns_ai_baseurl_' , (providerClassFor: pn) name
	)
	defaultBaseUrlForProvider: pn <String> ^<String> = (
		(* Sensible default base URL for first-time setup. Currently only
	   OpenAI-compatible has a non-empty default; other providers don't
	   have a URL concept (they hardcode their endpoints). *)
		
		pn = 'openai-compat' ifTrue: [ ^'http://localhost:11434/v1' ].
		^''
	)
	baseUrlForProvider: pn <String> ^<String> = (
		(* Read the configured base URL for pn; if nothing is stored, fall
	   back to defaultBaseUrlForProvider:. Returns '' for providers that
	   don't use a base URL. *)
		
		| stored |
		stored:: [ js localStorage getItem: (baseUrlStorageKeyFor: pn) ] on: Exception
			do: [:e | nil ].
		(stored isNil or: [ stored isEmpty ]) ifTrue: [
				^defaultBaseUrlForProvider: pn
			].
		^stored
	)
	public defaultChatDocumentOrCreate ^<Document | UndefinedObject> = (
		| activeName entry key doc |
		activeName:: [ js localStorage getItem: 'ns_ai_active_chat_doc' ] on: Exception
			do: [:e | nil ].
		activeName isNil ifTrue: [
				activeName:: 'Chat'.
				[ js localStorage setItem: 'ns_ai_active_chat_doc' to: 'Chat' ] on: Exception
					do: [:e | ]
			].
		entry:: Root at: activeName asSymbol ifAbsent: [ nil ].
		entry isNil ifFalse: [
				entry isKindOfChatDocument ifTrue: [ ^entry ].
				^nil
			].
		key:: apiKeyForProviderOrNil: 'anthropic'.
		key isNil ifTrue: [ ^nil ].
		doc:: createChatNamed: activeName
			provider: 'anthropic'
			model: 'claude-sonnet-4-6'.
		Root at: activeName asSymbol put: doc.
		^doc
	)
	installFocusDescription: aBlock validator: aValidator = (
		currentFocusBlock:: aBlock.
		currentFocusValidator:: aValidator
	)
	public setClassFocusOn: cdm = (
		| qname |
		qname:: qualifiedNameOf: cdm.
		focusKind:: #class.
		focusClassPath:: qname.
		focusSide:: nil.
		focusSelector:: nil.
		clearHistoricalFocusFields.
		installFocusDescription: [ 'Class: ' , qname ]
			validator: [ classStillExists: cdm ]
	)
	public setClassHeaderFocusOn: cdm = (
		| qname |
		qname:: qualifiedNameOf: cdm.
		focusKind:: #classHeader.
		focusClassPath:: qname.
		focusSide:: nil.
		focusSelector:: nil.
		clearHistoricalFocusFields.
		installFocusDescription: [ 'Class header (factory + slots) of class ' , qname ]
			validator: [ classStillExists: cdm ]
	)
	public setMethodFocusOn: cdm side: side selector: sel = (
		| qname selSym |
		qname:: qualifiedNameOf: cdm.
		selSym:: sel asSymbol.
		focusKind:: #method.
		focusClassPath:: qname.
		focusSide:: side.
		focusSelector:: selSym.
		clearHistoricalFocusFields.
		installFocusDescription: [
				'Method: ' , qname , ' (' , side , ' side) >> ' , selSym asString
			]
			validator: [ methodStillExists: cdm side: side selector: selSym ]
	)
	public setLazySlotFocusOn: cdm side: side name: name = (
		| qname nameSym |
		qname:: qualifiedNameOf: cdm.
		nameSym:: name asSymbol.
		focusKind:: #lazySlot.
		focusClassPath:: qname.
		focusSide:: side.
		focusSelector:: nameSym.
		clearHistoricalFocusFields.
		installFocusDescription: [
				'Lazy slot: ' , qname , ' (' , side , ' side) >> ' , nameSym asString
			]
			validator: [ lazySlotStillExists: cdm side: side name: nameSym ]
	)
	clearHistoricalFocusFields = (
		focusSha_slot:: nil.
		focusHistoricalSource_slot:: nil
	)
	public setHistoryFocusOnEntry: entrySubject = (
		(* Focus on a historical version of a method / lazy slot / class
	   header. Dispatches on the entry's memberMirror kind so the
	   focusKind / focusClassPath / focusSide / focusSelector match the
	   corresponding live focus, then layers on the sha and a snapshot of
	   the version's source. The structured focus carries enough for the
	   brain-button highlight to compare across rebuilds and for the read
	   tools to fan out to the historical source. *)
		
		| mirror shortSha header source |
		mirror:: entrySubject memberMirror.
		source:: entrySubject versionSource.
		focusSha_slot:: entrySubject sha.
		focusHistoricalSource_slot:: source.
		shortSha:: entrySubject shortSha.
		mirror isKindOfMethodMirror ifTrue: [
				| cdm side selSym qname |
				cdm:: mirror definingMixin declaration.
				side:: mirror definingMixin isMeta ifTrue: [ 'class' ]
					ifFalse: [ 'instance' ].
				selSym:: mirror name.
				qname:: qualifiedNameOf: cdm.
				focusKind:: #method.
				focusClassPath:: qname.
				focusSide:: side.
				focusSelector:: selSym.
				header:: 'Method (historical version @' , shortSha , '): ' , qname , ' (' , side , ' side) >> ' , selSym asString.
				^installHistoricalFocusDescription: header
					source: source
					entry: entrySubject
			].
		mirror isKindOfLazySlotMirror ifTrue: [
				| cdm side nameSym qname |
				cdm:: mirror definingMixin declaration.
				side:: mirror definingMixin isMeta ifTrue: [ 'class' ]
					ifFalse: [ 'instance' ].
				nameSym:: mirror name.
				qname:: qualifiedNameOf: cdm.
				focusKind:: #lazySlot.
				focusClassPath:: qname.
				focusSide:: side.
				focusSelector:: nameSym.
				header:: 'Lazy slot (historical version @' , shortSha , '): ' , qname , ' (' , side , ' side) >> ' , nameSym asString.
				^installHistoricalFocusDescription: header
					source: source
					entry: entrySubject
			].
		mirror isKindOfClassDeclarationMirror ifTrue: [
				| qname |
				qname:: qualifiedNameOf: mirror.
				focusKind:: #classHeader.
				focusClassPath:: qname.
				focusSide:: nil.
				focusSelector:: nil.
				header:: 'Class header (historical version @' , shortSha , ') of class ' , qname.
				^installHistoricalFocusDescription: header
					source: source
					entry: entrySubject
			]
	)
	installHistoricalFocusDescription: header source: source entry: entrySubject = (
		(* The description handed to current_focus combines an identity line,
	   the version's source, and an explicit note that source-writing
	   tools install changes as the new live version (the existing
	   Make Live semantic). The validator is a no-op true: git blobs are
	   immutable and we hold the snapshot, so the focus never goes
	   stale. *)
		
		| commitMsg dateStr description body lf |
		lf:: String fromRunes: {10. }.
		commitMsg:: firstLineOfMessage: entrySubject commitMessage.
		dateStr:: formatHistoryTimestamp: entrySubject commitTimestamp.
		body:: header , lf , 'Committed ' , dateStr , ': ' , commitMsg , lf , lf , source , lf , lf , 'Note: this is a read-only historical version. Tools that write source ' , '(e.g. set_member_source, propose_changes) install changes as the new ' , 'live version, similar to clicking Make Live.'.
		description:: body.
		installFocusDescription: [ description ] validator: [ true ]
	)
	firstLineOfMessage: msg = (
		| lf idx |
		lf:: String fromRunes: {10. }.
		idx:: msg indexOf: lf.
		^idx = 0 ifTrue: [ msg ] ifFalse: [ msg copyFrom: 1 to: idx - 1 ]
	)
	formatHistoryTimestamp: tsSeconds = (
		(* The alien bridge truncates Newspeak Integer to 32 bits when
	   handing it to JS, so force Float arithmetic via asFloat. *)
		
		| Date |
		Date:: js global at: 'Date'.
		^(Date new: tsSeconds asFloat * 1000) toLocaleString
	)
	public isFocusedOnHistory: memberMirror sha: sha ^<Boolean> = (
		(* Brain-button highlight predicate for a historical entry. Matches
	   when (a) the sha matches, AND (b) the live identity (kind +
	   class path + side + selector) matches the entry's memberMirror's
	   corresponding live identity. The mirror is the authority on the
	   qualified name, so we recompute it here rather than storing
	   redundant fields. *)
		
		focusSha_slot isNil ifTrue: [ ^false ].
		focusSha_slot = sha ifFalse: [ ^false ].
		memberMirror isKindOfMethodMirror ifTrue: [
				| cdm side |
				cdm:: memberMirror definingMixin declaration.
				side:: memberMirror definingMixin isMeta ifTrue: [ 'class' ]
					ifFalse: [ 'instance' ].
				^isFocusedOnMethod: cdm side: side selector: memberMirror name
			].
		memberMirror isKindOfLazySlotMirror ifTrue: [
				| cdm side |
				cdm:: memberMirror definingMixin declaration.
				side:: memberMirror definingMixin isMeta ifTrue: [ 'class' ]
					ifFalse: [ 'instance' ].
				^isFocusedOnLazySlot: cdm side: side name: memberMirror name
			].
		memberMirror isKindOfClassDeclarationMirror ifTrue: [
				^isFocusedOnClassHeader: memberMirror
			].
		^false
	)
	public setTestRunFocusOn: configClass = (
		(* Focus on a test run for the given test configuration class.
	   The argument is the underlying Class object (not a mirror) — that's
	   what TestingInProgressSubject and TestingOutcomeSubject carry. *)
		
		| cdm qname |
		cdm:: (ClassMirror reflecting: configClass) mixin declaration.
		qname:: qualifiedNameOf: cdm.
		focusKind:: #testRun.
		focusClassPath:: qname.
		focusSide:: nil.
		focusSelector:: nil.
		clearHistoricalFocusFields.
		installFocusDescription: [ 'Test results: ' , qname ]
			validator: [ classStillExists: cdm ]
	)
	public isFocusedOnTestRunClass: configClass ^<Boolean> = (
		focusKind = #testRun ifFalse: [ ^false ].
		^focusClassPath = (qualifiedNameOf: (ClassMirror reflecting: configClass) mixin declaration)
	)
	public setDocumentFocusOn: doc = (
		(* Focus on an Ampleforth document (including ChatDocuments). Identity
	   is the doc's name; the validator confirms a doc with that name still
	   lives in Root and is the same object. *)
		
		| docName |
		docName:: doc name.
		focusKind:: #document.
		focusClassPath:: docName.
		focusSide:: nil.
		focusSelector:: nil.
		clearHistoricalFocusFields.
		installFocusDescription: [ 'Document: ' , docName ]
			validator: [ (Root at: docName asSymbol ifAbsent: [ nil ]) = doc ]
	)
	public isFocusedOnDocument: doc ^<Boolean> = (
		focusKind = #document ifFalse: [ ^false ].
		^focusClassPath = doc name
	)
	public setEvaluatorFocusOnSubject: evaluatorSubject = (
		(* Focus on an evaluator. evaluatorSubject is the EvaluatorSubject the
	   brain belongs to — it owns the mirror (the receiver of evaluations:
	   ObjectMirror for workspaces/inspectors, ActivationMirror for method
	   evaluators and debugger frames) AND the results list shown in the
	   IDE evaluator pane.
	   The 'focus' id in the object registry resolves dynamically to the
	   mirror, and evaluate's default in_id is 'focus' whenever evaluator
	   focus is active, so the AI's evaluations route through this receiver
	   without further configuration.
	   When the underlying mirror is an ActivationMirror (method evaluator,
	   lazy-slot evaluator, or debugger frame) we also register it as
	   an 'aN' so debugger tools can refer to it by id. *)
		
		| mirror |
		mirror:: evaluatorSubject model mirror.
		focusKind:: #evaluator.
		focusClassPath:: nil.
		focusSide:: nil.
		focusSelector:: nil.
		focusEvaluatorMirror_slot:: mirror.
		focusEvaluatorSubject_slot:: evaluatorSubject.
		clearHistoricalFocusFields.
		mirror isKindOfActivationMirror ifTrue: [ registerActivation: mirror ].
		installFocusDescription: [
				'Evaluator (' , (evaluatorDescription: mirror) , ')'
			]
			validator: [ evaluatorMirrorStillValid: mirror ]
	)
	evaluatorMirrorStillValid: mirror ^<Boolean> = (
		(* For ActivationMirror, the activation must not have completed; once it
	   has, evaluating against it is meaningless. For ObjectMirror, the
	   reflectee stays alive as long as the mirror holds it, so we treat
	   it as always valid. *)
		
		^[
			mirror isKindOfActivationMirror ifTrue: [ mirror isUncontinuable not ]
				ifFalse: [ true ]
		] on: Error do: [:e | false ]
	)
	evaluatorDescription: mirror ^<String> = (
		^[
			mirror isKindOfActivationMirror ifTrue: [
					^'activation: ' , ([ mirror method name asString ] on: Error
						do: [:e | '(unknown method)' ])
				].
			'object: ' , ([ mirror getClass mixin name asString ] on: Error
				do: [:e | '(unknown class)' ])
		] on: Error do: [:e | 'unknown' ]
	)
	public isFocusedOnEvaluatorMirror: mirror ^<Boolean> = (
		focusKind = #evaluator ifFalse: [ ^false ].
		
		(* Use identity-aware mirror equality. ObjectMirror>>= and
	   ActivationMirror>>= both compare the underlying reflectee, which
	   is what we want. *)
		^focusEvaluatorMirror_slot = mirror
	)
	public isFocusedOnClass: cdm ^<Boolean> = (
		focusKind = #class ifFalse: [ ^false ].
		^focusClassPath = (qualifiedNameOf: cdm)
	)
	public isFocusedOnClassHeader: cdm ^<Boolean> = (
		focusKind = #classHeader ifFalse: [ ^false ].
		^focusClassPath = (qualifiedNameOf: cdm)
	)
	public isFocusedOnMethod: cdm side: side selector: sel ^<Boolean> = (
		focusKind = #method ifFalse: [ ^false ].
		focusClassPath = (qualifiedNameOf: cdm) ifFalse: [ ^false ].
		focusSide = side ifFalse: [ ^false ].
		^focusSelector = sel asSymbol
	)
	public isFocusedOnLazySlot: cdm side: side name: name ^<Boolean> = (
		focusKind = #lazySlot ifFalse: [ ^false ].
		focusClassPath = (qualifiedNameOf: cdm) ifFalse: [ ^false ].
		focusSide = side ifFalse: [ ^false ].
		^focusSelector = name asSymbol
	)
	public classStillExists: cdm ^<Boolean> = (
		^[ (resolveClassPath: (qualifiedNameOf: cdm)) = cdm ] on: Error
			do: [:e | false ]
	)
	public methodStillExists: cdm side: side selector: sel ^<Boolean> = (
		^[
			| resolved mixin |
			resolved:: resolveClassPath: (qualifiedNameOf: cdm).
			resolved = cdm and: [
					mixin:: side = 'class' ifTrue: [ resolved classSide ]
						ifFalse: [ resolved instanceSide ].
					(findMethodMirrorNamed: sel inMixin: mixin) isNil not
				]
		] on: Error do: [:e | false ]
	)
	public lazySlotStillExists: cdm side: side name: name ^<Boolean> = (
		^[
			| resolved mixin |
			resolved:: resolveClassPath: (qualifiedNameOf: cdm).
			resolved = cdm and: [
					mixin:: side = 'class' ifTrue: [ resolved classSide ]
						ifFalse: [ resolved instanceSide ].
					(findLazySlotMirrorNamed: name inMixin: mixin) isNil not
				]
		] on: Error do: [:e | false ]
	)
	public clearFocus = (
		currentFocusBlock:: nil.
		currentFocusValidator:: nil.
		focusKind:: nil.
		focusClassPath:: nil.
		focusSide:: nil.
		focusSelector:: nil.
		focusEvaluatorMirror_slot:: nil.
		focusEvaluatorSubject_slot:: nil.
		focusSha_slot:: nil.
		focusHistoricalSource_slot:: nil
	)
	public captureFocusInto: chatSubject = (
		(* Snapshot the module-global live focus (just set by the brain button's
	   setClassFocusOn:/setMethodFocusOn:/etc.) into chatSubject's per-chat
	   ChatFocus, so this chat's current_focus reports it regardless of later brain
	   clicks elsewhere (M2a). The module global stays only as the click-staging
	   source. Guarded: only doc-chat subjects carry a ChatFocus. *)

		([ chatSubject isKindOfIDEChatDocumentSubject ] on: Exception do: [:e | false ])
			ifTrue: [
				chatSubject focus installBlock: currentFocusBlock
					validator: currentFocusValidator
			]
	)
	public activeChatHolder = (
		^activeChatHolder_slot
	)
	public activeChatHolderPage = (
		^activeChatHolderPage_slot
	)
	public activeChatHolder: aChatHolder page: aPageSubject = (
		activeChatHolder_slot:: aChatHolder.
		activeChatHolderPage_slot:: aPageSubject
	)
	public chatLauncher = (
		(* Toolbar AI-chat entry point. Navigates to the ACTIVE CHAT DOC's
	   full document view (Ampleforth contents with chatControls,
	   thinkingOrModelPicker, userInputEditor structural amplets, and
	   chat turns as HTML sections). This is the canonical home of the
	   chat — the chat is a first-class IDE entity that lives in Root
	   with a name, and the toolbar is a shortcut to it.

	   Distinct from ensureSharedChat, which the per-presenter brain
	   buttons use to render an ephemeral inline ChatPresenter region.
	   Both reach the same underlying conversation (the Session backing
	   currentChatSubject_slot); the difference is presentation.

	   Resolution order:
	     1. If currentChatSubject_slot is an IDEChatDocumentSubject —
	        the common case after any prior chat-doc visit or startChat
	        — return a DocumentSubject on its document.
	     2. Legacy fallback: if it's some other (non-doc-bound) chat
	        subject, return it directly so the toolbar still works.
	     3. No cached chat at all: build a setup subject. If a key is
	        already stored, run startChat (which creates the doc and
	        returns a DocumentSubject for it). Otherwise return the
	        setup subject so the user can configure. *)
		
		| subj setup chatDocOrSetup |
		subj:: currentChatSubject_slot.
		subj isKindOfIDEChatDocumentSubject ifTrue: [
				^ide documents DocumentSubject onModel: subj document
			].
		subj isNil ifFalse: [ ^subj ].
		setup:: IDEChatSetupSubject onModel: AnthropicProvider.
		setup apiKey isEmpty ifTrue: [ ^setup ].
		chatDocOrSetup:: setup startChat.
		chatDocOrSetup isNil ifTrue: [ ^setup ].
		^chatDocOrSetup
	)
	public ensureSharedChat = (
		(* Return whatever subject the brain-button should navigate to next:
	   - If a chat is already current, reuse it — keeps a single rolling
	     conversation across brain clicks.
	   - Else restore the last chat from the reload hint if it still exists, and
	     make it current. (Building a chat subject no longer retargets on render —
	     M1 — so without this the brain button would create a fresh chat on every
	     reload instead of resuming the last one.)
	   - Otherwise we need a configured provider. If the Anthropic API key is still
	     empty, return the setup Subject; if a key is stored, fall through to
	     startChat which builds the doc + subject. *)

		| activeName entry setup <IDEChatSetupSubject> chat |
		currentChatSubject_slot isNil ifFalse: [ ^currentChatSubject_slot ].
		activeName:: [ js localStorage getItem: 'ns_ai_active_chat_doc' ] on: Exception
			do: [:e | nil ].
		activeName isNil ifFalse: [
				entry:: Root at: activeName asSymbol ifAbsent: [ nil ].
				(entry isNil not and: [
						[ entry isKindOfChatDocument ] on: Exception do: [:e | false ]]) ifTrue: [
						^makeCurrentChat: entry
					]
			].
		setup:: IDEChatSetupSubject onModel: AnthropicProvider.
		setup apiKey isEmpty ifTrue: [ ^setup ].
		chat:: setup startChat.
		chat isNil ifTrue: [ ^setup ].

		(* startChat goes through newChatSubjectFor:, which has already cached. *)
		^currentChatSubject_slot
	)
	chatDocumentsInRoot ^<List[Document]> = (
		(* Every chat document currently in Root, in Root's insertion order
	   (roughly creation order). A chat document is a Document answering
	   isKindOfChatDocument. Used by ChatControlsPresenter and the regular
	   chat presenter's switcher so the two stay in sync. *)
		
		| docs |
		docs:: List new.
		Root keysAndValuesDo: [:k :v |
				([ v isKindOfChatDocument ] on: Exception do: [:e | false ]) ifTrue: [
						docs add: v
					]
			].
		^docs
	)
	chatSwitchMenuActions ^<List> = (
		(* {label. action} pairs for a "switch chat" dropdown: one per
	   ChatDocument in Root, each navigating the IDE to that chat's full
	   document view. The previously-open chat keeps its Session, so its
	   conversation resumes when reselected. The action blocks reach `ide`
	   lexically, so this is reusable from any nested presenter. *)
		
		^chatDocumentsInRoot collect: [:doc |
				{doc name. [
					(* Explicit switch → make the selected chat current (render no longer
				   retargets — M1), then navigate to its full document view. *)
					makeCurrentChat: doc.
					ide browsing navigateTo: (ide documents DocumentSubject onModel: doc)
				]. }
			]
	)
	openNewChatSetup = (
		(* Navigate to the chat-setup screen to start a new chat (with its own
	   provider/model/name); startChat creates a fresh Root ChatDocument
	   without disturbing any existing chat. Shared by the doc's "New Chat"
	   button and the regular presenter's New-chat button. *)
		
		ide browsing navigateTo: (IDEChatSetupSubject onModel: AnthropicProvider)
	)
	makeCurrentChat: doc <Document> ^<IDEChatDocumentSubject> = (
		(* Deliberately make `doc` the current targeted chat: its subject becomes
	   what the inline chat region (ensureSharedChat) and the toolbar default to,
	   and it is recorded as the default-on-reload chat doc in localStorage. This is
	   the ONLY render-independent retarget (used by the presenter chat switcher);
	   building the subject (chatSubjectFor:) no longer retargets, so other live
	   chats are left alone. *)

		| subject |
		subject:: doc chatSubject.
		currentChatSubject_slot:: subject.
		[ js localStorage setItem: 'ns_ai_active_chat_doc' to: doc name ] on: Exception
			do: [:e | ].
		^subject
	)
	public chatControlsFor: doc <Document> ^<Presenter> = (
		^ChatControlsPresenter onSubject: doc
	)
	public thinkingPickerFor: doc <Document> ^<Presenter> = (
		^ChatStatusPresenter onSubject: (chatSubjectFor: doc)
	)
	public inputEditorFor: doc <Document> ^<Presenter> = (
		^ChatInputPresenter onSubject: (chatSubjectFor: doc)
	)
	public chatSubjectFor: doc <Document> ^<IDEChatDocumentSubject> = (
		(* Build/cache the doc's IDEChatDocumentSubject (and its Session) on the
	   doc's chatSubjectSlot, and return it. This is the RENDER path (called by
	   thinkingPickerFor:/inputEditorFor: every time a chat doc's amplets render),
	   so it must NOT retarget the current chat or touch localStorage — otherwise
	   transcluding/rendering one chat doc would steal "current" from another live
	   chat. Retargeting is deliberate only: makeCurrentChat: / startChat (M1). *)

		doc maxAmpletCount < 3 ifTrue: [ doc maxAmpletCount: 3 ].
		doc chatSubjectSlot isNil ifTrue: [
				| fh |
				fh:: ChatFocus onDoc: doc.
				doc chatSubjectSlot: (IDEChatDocumentSubject onChatDocument: doc
						session: (createFreshSessionFor: doc focus: fh)
						focus: fh)
			].
		^doc chatSubjectSlot
	)
	createFreshSessionFor: doc <Document> focus: focus <ChatFocus> ^<Session> = (
		(* Build a Session from the chat doc's stored provider/model (read from its
	   HTML so they round-trip through save/load). The session's tools report
	   `focus` for current_focus — the per-chat focus shared with this doc's
	   IDEChatDocumentSubject (M2a). Mirrors old ChatDocument>>createFreshSession. *)
		
		| pn mn cls key provider session |
		pn:: chatProviderOf: doc.
		mn:: chatModelOf: doc.
		key:: pn = 'openai-compat' ifTrue: [
				(apiKeyForProviderOrNil: pn) isNil ifTrue: [ '' ]
					ifFalse: [ apiKeyForProvider: pn ]
			]
			ifFalse: [ apiKeyForProvider: pn ].
		cls:: providerClassFor: pn.
		provider:: pn = 'openai-compat' ifTrue: [
				cls apiKey: key model: mn baseUrl: (baseUrlForProvider: pn)
			]
			ifFalse: [ cls apiKey: key model: mn ].
		session:: Session provider: provider tools: (toolsForProvider: provider focus: focus).
		session systemPrompt: newspeakSystemPrompt.
		^session
	)
	chatProviderOf: doc <Document> ^<String> = (
		^chatMetaOf: doc attr: 'data-chat-provider' ifAbsent: 'anthropic'
	)
	chatModelOf: doc <Document> ^<String> = (
		^chatMetaOf: doc attr: 'data-chat-model' ifAbsent: 'claude-sonnet-4-6'
	)
	chatMetaOf: doc <Document> attr: attr <String> ifAbsent: default <String> ^<String> = (
		(* Read a data- attribute off the chat doc's self_ampleforth wrapper.
	   provider/model live there so they survive save/load like any HTML. *)
		
		| container wrappers wrapper v |
		container:: parseAmpletContainer: doc contents.
		wrappers:: container getElementsByClassName: 'self_ampleforth'.
		(wrappers at: 'length') = 0 ifTrue: [ ^default ].
		wrapper:: wrappers at: 0.
		(wrapper hasAttribute: attr) ifFalse: [ ^default ].
		v:: wrapper getAttribute: attr.
		(v isNil or: [ v isEmpty ]) ifTrue: [ ^default ].
		^v
	)
	public appendSection: text <String> role: role <String> into: doc <Document> = (
		(* Append one chat turn as a `chatTurn:role:` amplet, inserted just before
	   the model-machinery gap. The literal text + role ride in the amplet's
	   name expression (escaped via asAmpletTextLiteral:), so the turn is part
	   of the document's saved HTML and reconstructs on load via the ordinary
	   evaluateFragment: path — no chat-specific load code. Turns are thus
	   first-class, addressable amplets the user can interleave content between,
	   rather than opaque injected HTML. *)
		
		| container thinking gap jsDoc amplet ampletId parent expr |
		container:: parseAmpletContainer: doc contents.
		thinking:: findChatStructuralAmplet: 'thinkingOrModelPicker' in: container.
		thinking isNil ifTrue: [
				Error signal: 'Chat document is missing its structural amplets; cannot append turn'
			].
		gap:: ensureModelMachineryGap: container beforeThinking: thinking.
		jsDoc:: js global at: 'document'.
		doc maxAmpletCount: doc maxAmpletCount + 1.
		ampletId:: doc maxAmpletCount printString.
		expr:: 'chatTurn: ' , (asAmpletTextLiteral: text) , ' role: ' , (asAmpletTextLiteral: role).
		amplet:: jsDoc createElement: 'div'.
		amplet setAttribute: 'class' to: 'ampleforth'.
		amplet setAttribute: 'ampletId' to: ampletId.
		amplet setAttribute: 'name' to: expr.
		amplet setAttribute: 'contenteditable' to: 'false'.
		amplet setAttribute: 'style' to: 'display:block; margin:4px 0;'.
		parent:: gap at: 'parentNode'.
		parent insertBefore: amplet before: gap.
		doc mutateContentsTo: (container at: 'innerHTML')
	)
	public chatTurnText: t <String> role: r <String> ^<Fragment> = (
		(* The amplet value for a chatTurn:role: amplet: one chat turn as an
	   HTMLFragment (an amplet result must be a Hopscotch Fragment — the
	   amplet machinery sends `visual` to it). Mirrors ChatPresenter>>
	   messageFragment: visuals; text is HTML-escaped so code-bearing replies
	   (<, >, &) render literally rather than as markup. *)
		
		| labelText bg border fontStyle safe |
		r = 'user' ifTrue: [
				labelText:: 'You'.
				bg:: aiColors userTurnBackground.
				border:: aiColors userTurnBorder.
				fontStyle:: 'italic'
			]
			ifFalse: [
				r = 'assistant' ifTrue: [
						labelText:: 'Assistant'.
						bg:: aiColors assistantTurnBackground.
						border:: aiColors assistantTurnBorder.
						fontStyle:: 'normal'
					]
					ifFalse: [
						labelText:: 'Error'.
						bg:: aiColors errorTurnBackground.
						border:: aiColors errorTurnBorder.
						fontStyle:: 'normal'
					]
			].
		safe:: htmlEscapeForDisplay: t.
		^HTMLFragment html: '<div style="display:flex; flex-direction:row; align-items:flex-start; border:1px solid ' , border , '; border-radius:6px; padding:8px 12px; margin:4px 0; background-color:' , bg , ';">' , '<div style="min-width:5em; max-width:5em; padding-right:1em; text-align:right; flex-shrink:0;"><strong>' , labelText , '</strong></div>' , '<div style="flex:1; min-width:0;"><span style="white-space:pre-wrap; font-style:' , fontStyle , ';">' , safe , '</span></div></div>'
	)
	jsReplaceAll: s <String> from: a <String> to: b <String> ^<String> = (
		(* Global literal string replace via native JS String.prototype.replaceAll.
	   psoup's String does NOT implement replaceAll:with: (that lives on the
	   JS-deploy KernelForJS String), so we wrap s as a JS String first — the
	   same idiom as Documents>>classSource. The native call returns a psoup
	   String, so each chained replace must re-wrap (hence this helper). *)
		
		^(JSString new: s) replaceAll: a with: b
	)
	asAmpletTextLiteral: s <String> ^<String> = (
		(* Wrap s as a Newspeak single-quoted string literal, doubling embedded
	   apostrophes, for embedding in an amplet name expression. The resulting
	   attribute's HTML escaping is handled by the DOM on setAttribute:/innerHTML
	   serialization and undone on load by getAttribute, so the expression
	   round-trips through save/load. Nil-safe: runs at append time inside a
	   Promise then: block (markComplete), where a DNU would corrupt the bridge. *)
		
		| safe |
		safe:: s isNil ifTrue: [ '' ] ifFalse: [ s ].
		^'''' , (jsReplaceAll: safe from: '''' to: '''''') , ''''
	)
	htmlEscapeForDisplay: s <String> ^<String> = (
		(* Escape &, <, > so turn text containing code renders literally in the
	   html: fragment rather than as markup. & first to avoid double-escaping.
	   Nil-safe (see asAmpletTextLiteral:). *)
		
		| r |
		r:: s isNil ifTrue: [ '' ] ifFalse: [ s ].
		r:: jsReplaceAll: r from: '&' to: '&amp;'.
		r:: jsReplaceAll: r from: '<' to: '&lt;'.
		r:: jsReplaceAll: r from: '>' to: '&gt;'.
		^r
	)
	public appendChangesetAmplet: id <String> into: doc <Document> = (
		(* Relocation of old ChatDocument>>appendChangesetAmpletFor:. Inserts a
	   `changesetPresenterFor: 'csN'` amplet before the model-machinery gap;
	   the doc's forwarder re-routes that expression back here on render. *)
		
		| container thinking gap jsDoc amplet ampletId parent expr |
		container:: parseAmpletContainer: doc contents.
		thinking:: findChatStructuralAmplet: 'thinkingOrModelPicker' in: container.
		thinking isNil ifTrue: [
				Error signal: 'Chat document is missing its structural amplets; cannot append amplet'
			].
		gap:: ensureModelMachineryGap: container beforeThinking: thinking.
		jsDoc:: js global at: 'document'.
		doc maxAmpletCount: doc maxAmpletCount + 1.
		ampletId:: doc maxAmpletCount printString.
		expr:: 'changesetPresenterFor: ' , (asAmpletTextLiteral: id).
		amplet:: jsDoc createElement: 'div'.
		amplet setAttribute: 'class' to: 'ampleforth'.
		amplet setAttribute: 'ampletId' to: ampletId.
		amplet setAttribute: 'name' to: expr.
		amplet setAttribute: 'contenteditable' to: 'false'.
		amplet setAttribute: 'style' to: 'display:block; margin:8px 0;'.
		parent:: gap at: 'parentNode'.
		parent insertBefore: amplet before: gap.
		doc mutateContentsTo: (container at: 'innerHTML')
	)
	public forgetCachedChangesetSubject: id <String> for: doc <Document> = (
		doc changesetSubjectsById removeKey: id ifAbsent: [ ]
	)
	public clearConversationFor: doc <Document> = (
		doc chatSubjectSlot isNil ifFalse: [ doc chatSubjectSlot session clearHistory ]
	)
	public invalidateChatAmpletCachesOn: editor = (
		(* Relocation of old ChatDocument>>invalidateAmpletCachesOn:. Drops every
	   cached amplet fragment/expression except the doc-identity entry so the
	   structural amplets re-evaluate (their state lives on the chat subject). *)
		
		| keysToRemove <List> |
		keysToRemove:: List new.
		editor fragmentMapping keysAndValuesDo: [:k :v |
				k = 'AmpleforthTargetDocument' ifFalse: [ keysToRemove add: k ]
			].
		keysToRemove do: [:k | editor fragmentMapping removeKey: k ].
		keysToRemove:: List new.
		editor expressionMapping keysAndValuesDo: [:k :v | keysToRemove add: k ].
		keysToRemove do: [:k | editor expressionMapping removeKey: k ]
	)
	public pendingChangesetIdsFor: doc <Document> ^<List[String]> = (
		(* Lazy-init the doc's pending-changeset list in the module (which has List
	   in scope; a DocumentHolder-nested chat class may not). Stored on the
	   doc's bare pendingChangesetIdsSlot. *)
		
		doc pendingChangesetIdsSlot isNil ifTrue: [
				doc pendingChangesetIdsSlot: List new
			].
		^doc pendingChangesetIdsSlot
	)
	public changesetSubjectsByIdFor: doc <Document> ^<Map[String, Object]> = (
		doc changesetSubjectsByIdSlot isNil ifTrue: [
				doc changesetSubjectsByIdSlot: Map new
			].
		^doc changesetSubjectsByIdSlot
	)
	chatTemplateClassBody ^<String> = (
		(* The shared class body every chat document carries (the "template"). It
	   holds only per-chat state slots + thin forwarders to the `…For: doc`
	   module methods above, so the real chat logic is single-sourced here and
	   evolves for all chats (old saved ones included). Emitted into the
	   `classBody="…"` attribute of the document wrapper by createChatNamed:…,
	   so it MUST contain no double-quote characters (single-quoted strings are
	   doubled per Newspeak literal rules). `ide` resolves lexically to
	   DocumentHolder's ide slot (= webIDE) where these per-doc classes nest. *)
		
		^'(
|
	public chatSubjectSlot ::= nil.
	public pendingChangesetIdsSlot ::= nil.
	public changesetSubjectsByIdSlot ::= nil.
|
) (
public isKindOfChatDocument ^ <Boolean> = ( ^true )
public chatSubject = ( ^ide aiSupport chatSubjectFor: self )
public session = ( ^chatSubject session )
public prepareForLiveViewRefresh: editor = ( ide aiSupport invalidateChatAmpletCachesOn: editor )
public chatControls = ( ^ide aiSupport chatControlsFor: self )
public thinkingOrModelPicker = ( ^ide aiSupport thinkingPickerFor: self )
public userInputEditor = ( ^ide aiSupport inputEditorFor: self )
public chatTurn: t role: r = ( ^ide aiSupport chatTurnText: t role: r )
public pendingChangesetIds = ( ^ide aiSupport pendingChangesetIdsFor: self )
public changesetSubjectsById = ( ^ide aiSupport changesetSubjectsByIdFor: self )
public appendUserSection: text = ( ide aiSupport appendSection: text role: ''user'' into: self )
public appendAssistantSection: text = ( ide aiSupport appendSection: text role: ''assistant'' into: self )
public appendErrorSection: text = ( ide aiSupport appendSection: text role: ''error'' into: self )
public appendChangesetAmpletFor: id = ( ide aiSupport appendChangesetAmplet: id into: self )
public forgetCachedChangesetSubjectFor: id = ( ide aiSupport forgetCachedChangesetSubject: id for: self )
public changesetPresenterFor: id = ( ^ide aiSupport changesetPresenter: id for: self )
public clearConversation = ( ide aiSupport clearConversationFor: self )
)'
	)
	chatShellInnerHTMLForName: n <String> provider: pn <String> model: mn <String> ^<String> = (
		(* The chat document body (becomes `contents`): an editable self_ampleforth
	   canvas carrying provider+model as data- attributes (so they round-trip
	   through save/load with no custom load hook) plus the three structural
	   amplets. Counterpart of old initialChatDocumentContents:. *)
		
		^'<div class="self_ampleforth" contenteditable="true" data-chat-provider="' , pn , '" data-chat-model="' , mn , '" style="border: 2px solid blue; resize: horizontal; overflow: auto; overflow-wrap: break-word; width: 40em;" onkeyup="updateRawHTML()" ondragover="((e) => {e.preventDefault();})(event)"> <!-- self_ampleforth -->
<h1>' , n , '</h1>
<div class="ampleforth" ampletId="1" name="chatControls" contenteditable="false"> </div>
<div class="modelMachineryGap" style="display:block; min-height:3em; padding:0.5em; margin:0.5em 0;"> </div>
<div class="ampleforth" ampletId="2" name="thinkingOrModelPicker" contenteditable="false"> </div>
<div class="ampleforth" ampletId="3" name="userInputEditor" contenteditable="false" style="display:block; width:100%; min-height:4em; margin-top:0.5em;"> </div>
</div>'
	)
	createChatNamed: n <String> provider: pn <String> model: mn <String> ^<Document> = (
		(* Create a chat as an ordinary per-document-class document (the
	   clone-template realization): build the standard document wrapper with the
	   chat template class body + the shell HTML, and hand it to the generic
	   public creator. The result is a Document subclass nested in DocumentHolder
	   — load-compatible by construction and listed like any document. Does NOT
	   bind into a namespace; the caller binds where it wants. *)
		
		| wrapper |
		wrapper:: '<div class = "ampleforthDocumentClass" name = "' , n , '" classBody = "' , chatTemplateClassBody , '"></div><div class = "ampleforthDocumentBody" edition="2">' , (chatShellInnerHTMLForName: n
			provider: pn
			model: mn) , '</div>'.
		^ide documents freshDocumentWithContents: wrapper
	)
	classDeclarationNamed: name <String> ^<ClassDeclarationMirror> = (
		| cls |
		cls:: Root at: name asSymbol
			ifAbsent: [ Error signal: 'Class not found: ' , name ].
		cls isKindOfBehavior ifFalse: [ Error signal: 'Not a class: ' , name ].
		^(ClassMirror reflecting: cls) mixin declaration
	)
	resolveNamespacePath: path <String> ^<Object> = (
		(* Navigate the namespace tree starting at Root. A leading 'Root.' segment
	   is optional. Returns the entry (which may be a Namespace, a class, a
	   Document, an Image, etc.). Signals an error if a segment is not found. *)
		
		| parts start current |
		parts:: path isEmpty ifTrue: [ {} ] ifFalse: [ path findTokens: '.' ].
		current:: Root.
		start:: (parts isEmpty not and: [ (parts at: 1) = 'Root' ]) ifTrue: [ 2 ]
			ifFalse: [ 1 ].
		start to: parts size
			do: [:i |
				| seg = parts at: i. |
				current:: current at: seg asSymbol
					ifAbsent: [ Error signal: 'Not found in namespace path: ' , seg ]
			].
		^current
	)
	kindOf: value <Object> ^<String> = (
		value isKindOfNamespace ifTrue: [ ^'namespace' ].
		value isKindOfBehavior ifTrue: [ ^'class' ].
		value isKindOfDocument ifTrue: [ ^'document' ].
		value isKindOfString ifTrue: [ ^'string' ].
		value isKindOfJSAlien ifTrue: [
				'IMG' = (value at: 'nodeName') ifTrue: [ ^'image' ].
				^'alien'
			].
		^'other'
	)
	public qualifiedNameOf: cdm <ClassDeclarationMirror> ^<String> = (
		(* Walks the enclosing-class chain to produce a dotted path,
	   e.g. "RuntimeForHopscotchForHTML.Platform.Images". *)
		
		| path enclosing |
		path:: cdm simpleName.
		enclosing:: cdm enclosingClass.
		[ enclosing isNil ] whileFalse: [
				path:: enclosing simpleName , '.' , path.
				enclosing:: enclosing enclosingClass
			].
		^path
	)
	resolveClassPath: path <String> ^<ClassDeclarationMirror> = (
		| parts cdm |
		parts:: path findTokens: '.'.
		cdm:: classDeclarationNamed: (parts at: 1).
		2 to: parts size
			do: [:i |
				| nestedName found |
				nestedName:: (parts at: i) asSymbol.
				found:: false.
				cdm instanceSide nestedClasses do: [:nc |
						nc simpleName = nestedName ifTrue: [
								cdm:: nc.
								found:: true
							]
					].
				found ifFalse: [
						Error signal: 'Nested class not found: ' , (parts at: i) , ' in ' , cdm simpleName
					]
			].
		^cdm
	)
	namespaceSubjectForPath: path <String> ^<Object> = (
		(* Build a NamespaceSubject for the namespace at the given dotted path,
	   or for Root if the path is empty or 'Root'. Raises an error if the
	   path resolves to something that is not a Namespace. *)
		
		| parts ns key |
		(path isEmpty or: [ path = 'Root' ]) ifTrue: [
				^ide browsing NamespaceSubject new
			].
		ns:: resolveNamespacePath: path.
		ns isKindOfNamespace ifFalse: [
				Error signal: path , ' is not a namespace (it is a ' , (kindOf: ns) , ')'
			].
		parts:: path findTokens: '.'.
		key:: (parts at: parts size) asSymbol.
		^ide browsing NamespaceSubject onModel: ns key: key
	)
	formatAccess: am ^<String> = (
		am = #public ifTrue: [ ^'public ' ].
		am = #private ifTrue: [ ^'private ' ].
		^''
	)
	freshChangesetId ^<String> = (
		nextChangesetIdNum:: nextChangesetIdNum + 1.
		^'cs' , nextChangesetIdNum printString
	)
	mixinForChange: change ^<Object> = (
		| cdm side |
		cdm:: resolveClassPath: (change at: 'class_name').
		side:: (change includesKey: 'side') ifTrue: [ change at: 'side' ]
			ifFalse: [ 'instance' ].
		^side = 'class' ifTrue: [ cdm classSide ] ifFalse: [ cdm instanceSide ]
	)
	findMethodMirrorNamed: selector <Symbol> inMixin: mixin ^<Object> = (
		mixin methods do: [:mm | mm name = selector ifTrue: [ ^mm ] ].
		^nil
	)
	findLazySlotMirrorNamed: selector <Symbol> inMixin: mixin ^<Object> = (
		mixin lazySlots do: [:ls | ls name = selector ifTrue: [ ^ls ] ].
		^nil
	)
	isMemberKind: kind ^<Boolean> = (
		^kind = 'add_or_replace_method' or: [
				kind = 'delete_method' or: [
						kind = 'add_or_replace_lazy_slot' or: [ kind = 'delete_lazy_slot' ]
					]
			]
	)
	validateChange: change ^<Object> = (
		(* Returns a Map record of the validated change. Raises if invalid. *)
		
		| kind record |
		kind:: change at: 'kind'.
		record:: Map new.
		record at: 'kind' put: kind.
		record at: 'class_name' put: (change at: 'class_name').
		(isMemberKind: kind) ifTrue: [
				| side mixin sel old |
				side:: (change includesKey: 'side') ifTrue: [ change at: 'side' ]
					ifFalse: [ 'instance' ].
				(side = 'instance' or: [ side = 'class' ]) ifFalse: [
						Error signal: 'side must be "instance" or "class", got: ' , side
					].
				record at: 'side' put: side.
				mixin:: mixinForChange: change.
				kind = 'add_or_replace_method' ifTrue: [
						record at: 'source' put: (change at: 'source').
						^record
					].
				kind = 'add_or_replace_lazy_slot' ifTrue: [
						record at: 'source' put: (change at: 'source').
						^record
					].
				kind = 'delete_method' ifTrue: [
						sel:: (change at: 'selector') asSymbol.
						record at: 'selector' put: sel.
						old:: findMethodMirrorNamed: sel inMixin: mixin.
						old isNil ifTrue: [
								Error signal: 'No method ' , sel , ' on the ' , side , ' side of ' , (record at: 'class_name')
							].
						record at: 'old_source' put: old source.
						^record
					].
				kind = 'delete_lazy_slot' ifTrue: [
						sel:: (change at: 'selector') asSymbol.
						record at: 'selector' put: sel.
						old:: findLazySlotMirrorNamed: sel inMixin: mixin.
						old isNil ifTrue: [
								Error signal: 'No lazy slot ' , sel , ' on the ' , side , ' side of ' , (record at: 'class_name')
							].
						record at: 'old_source' put: old source.
						^record
					]
			].
		kind = 'set_class_header' ifTrue: [
				| cdm |
				record at: 'source' put: (change at: 'source').
				cdm:: resolveClassPath: (record at: 'class_name').
				record at: 'old_source' put: cdm header source.
				^record
			].
		kind = 'add_or_replace_nested_class' ifTrue: [
				
				(* class_name is the enclosing class (must already exist). *)
				record at: 'source' put: (change at: 'source').
				resolveClassPath: (record at: 'class_name').
				^record
			].
		kind = 'delete_nested_class' ifTrue: [
				| segments cdm |
				segments:: (record at: 'class_name') findTokens: '.'.
				segments size < 2 ifTrue: [
						Error signal: 'delete_nested_class requires a nested class path (got top-level: ' , (record at: 'class_name') , '). Top-level deletion is not supported by this tool.'
					].
				cdm:: resolveClassPath: (record at: 'class_name').
				record at: 'old_source' put: cdm source.
				^record
			].
		kind = 'add_top_level_class' ifTrue: [
				| name existing |
				record at: 'source' put: (change at: 'source').
				name:: change at: 'class_name'.
				existing:: Root at: name asSymbol ifAbsent: [ nil ].
				existing isNil ifFalse: [
						Error signal: 'A top-level entry named ' , name , ' already exists in Root'
					].
				^record
			].
		Error signal: 'Unknown change kind: ' , kind
	)
	enqueuePendingChangesetId: id <String> forChat: subj = (
		(* Stage id for the next markComplete of `subj` — the chat whose session
	   PROPOSED the changeset, NOT the global current chat, so a proposal made
	   during one session does not surface in whichever chat happens to be current
	   (M2b). The same id has to surface in both presenter flavours of the chat —
	   the doc view (amplets inserted into the chat doc HTML by
	   IDEChatDocumentSubject>>markComplete) and the inline view (per-message-index
	   map populated by IDEChatSubject>>markComplete and read by
	   IDEChatPresenter>>messagesArea). Push to BOTH queues so a doc-backed chat
	   displayed inline still shows the proposals; each markComplete override drains
	   its own list. *)

		subj isNil ifTrue: [ ^self ].

		(* Always populate the subject-level queue (inherited by both
	   inline and doc-backed subjects) — that's what the inline
	   presenter reads. *)
		subj isKindOfIDEChatSubject ifTrue: [ subj pendingChangesetIds add: id ].

		(* And, for doc-backed subjects, also populate the document-level
	   queue so the existing amplet pipeline keeps working. *)
		subj isKindOfIDEChatDocumentSubject ifTrue: [
				subj document pendingChangesetIds add: id
			]
	)
	proposingChatFor: focus <ChatFocus> ^<Object | UndefinedObject> = (
		(* The chat subject that owns `focus`'s session — the proposing chat. Falls
	   back to the global current for doc-less sessions (focus has no chatDoc). By
	   the time a tool fires, the doc's chatSubjectSlot is set (M2b). *)
		focus chatDoc isNil ifTrue: [ ^currentChatSubject_slot ].
		^focus chatDoc chatSubjectSlot
	)
	broadcastChangeAppliedBy: applier <Object | UndefinedObject> records: records <List> = (
		(* M3: tell every OTHER open chat (one with a live session) that the codebase
	   changed, so its AI re-reads instead of trusting cached source. The applier
	   already knows, so it is skipped. The notice rides each recipient's NEXT-turn
	   system prompt (Session>>addSystemNotice:) — model context only, not a visible
	   chat bubble. Diffs are not live-updated (changeset staleness is left as-is). *)

		| desc |
		desc:: changeSummaryFor: records.
		chatDocumentsInRoot do: [:doc |
				(* Each doc fully guarded: a broadcast failure must NEVER break the
			   apply that triggered it. NB: Hopscotch Subjects don't understand ~~,
			   so identity-exclusion of the applier uses ~= (they define =). *)
				[
					| subj |
					subj:: doc chatSubjectSlot.
					(subj isNil not and: [ subj ~= applier ]) ifTrue: [
							subj session addSystemNotice: 'Another AI session just changed the codebase ('
								, desc
								, '). Anything you read earlier may be stale — re-read any class or member you rely on before acting.'
						]
				] on: Exception do: [:e | nil ]
			]
	)
	changeSummaryFor: records <List> ^<String> = (
		(* Distinct top-level/target class names touched by a changeset, for the
	   broadcast notice. Best-effort: skip records without a class_name. *)

		| names |
		names:: List new.
		records do: [:r |
				| n |
				n:: [ r at: 'class_name' ] on: Exception do: [:e | nil ].
				(n isNil not and: [ (names includes: n) not ]) ifTrue: [ names add: n ]
			].
		names isEmpty ifTrue: [ ^'unspecified changes' ].
		^names inject: 'classes: ' into: [:acc :n |
				acc = 'classes: ' ifTrue: [ acc , n ] ifFalse: [ acc , ', ' , n ] ]
	)
	summarizeChangesetId: id <String> records: records <List> ^<String> = (
		(* Short, structured-y summary returned to the model as the tool
	   result. The user sees the proper structured diff in the chat doc
	   via the embedded ChangesetPresenter; the model only needs enough
	   to reference the proposal in follow-up turns. *)
		
		| newClasses changedMembers removedMembers result |
		newClasses:: List new.
		changedMembers:: List new.
		removedMembers:: List new.
		records do: [:r |
				| kind cn side selOrNew |
				kind:: r at: 'kind'.
				cn:: r at: 'class_name'.
				side:: (r includesKey: 'side') ifTrue: [ r at: 'side' ]
					ifFalse: [ 'instance' ].
				kind = 'add_top_level_class' ifTrue: [ newClasses add: cn ].
				kind = 'add_or_replace_method' ifTrue: [
						selOrNew:: [ (extractMethodSelectorFromSource: (r at: 'source')) asString ] on: Exception
							do: [:e | '?' ].
						changedMembers add: cn , (side = 'class' ifTrue: [ ' class>>' ]
								ifFalse: [ '>>' ]) , selOrNew
					].
				kind = 'add_or_replace_lazy_slot' ifTrue: [
						selOrNew:: [
							(extractLazySlotSelectorFromSource: (r at: 'source')) asString
						] on: Exception do: [:e | '?' ].
						changedMembers add: cn , (side = 'class' ifTrue: [ ' class>>' ]
								ifFalse: [ '>>' ]) , selOrNew , ' (slot)'
					].
				kind = 'set_class_header' ifTrue: [ changedMembers add: cn , ' (header)' ].
				kind = 'add_or_replace_nested_class' ifTrue: [
						changedMembers add: cn , '.<nested>'
					].
				kind = 'delete_method' ifTrue: [
						removedMembers add: cn , (side = 'class' ifTrue: [ ' class>>' ]
								ifFalse: [ '>>' ]) , (r at: 'selector') asString
					].
				kind = 'delete_lazy_slot' ifTrue: [
						removedMembers add: cn , (side = 'class' ifTrue: [ ' class>>' ]
								ifFalse: [ '>>' ]) , (r at: 'selector') asString , ' (slot)'
					].
				kind = 'delete_nested_class' ifTrue: [ removedMembers add: cn ]
			].
		result:: 'Staged changeset ' , id , ' (' , records size printString , (records size = 1 ifTrue: [
				' change).'
			]
			ifFalse: [ ' changes).' ]).
		newClasses isEmpty ifFalse: [
				result:: result , ' New: ' , (joinStrings: newClasses with: ', ') , '.'
			].
		changedMembers isEmpty ifFalse: [
				result:: result , ' Changed: ' , (joinStrings: changedMembers with: ', ') , '.'
			].
		removedMembers isEmpty ifFalse: [
				result:: result , ' Removed: ' , (joinStrings: removedMembers with: ', ') , '.'
			].
		result:: result , ' The IDE is rendering a structured diff inline; wait for the user to review and explicitly approve (or click Apply themselves) before calling apply_changeset.'.
		^result
	)
	joinStrings: strs <List[String]> with: sep <String> ^<String> = (
		| result first |
		result:: ''.
		first:: true.
		strs do: [:s |
				first ifTrue: [
						result:: s.
						first:: false
					]
					ifFalse: [ result:: result , sep , s ]
			].
		^result
	)
	formatChangesetId: id records: records ^<String> = (
		| result count |
		count:: records size.
		result:: 'Changeset ' , id , ' (' , count printString , (count = 1 ifTrue: [
				' change):'
			]
			ifFalse: [ ' changes):' ]) , '\n'.
		records do: [:r |
				| kind sideStr |
				kind:: r at: 'kind'.
				sideStr:: (r includesKey: 'side') ifTrue: [
						' (' , (r at: 'side') , ' side)'
					]
					ifFalse: [ '' ].
				result:: result , '\n[' , kind , '] ' , (r at: 'class_name') , sideStr.
				(kind = 'delete_method' or: [ kind = 'delete_lazy_slot' ]) ifTrue: [
						result:: result , ' >> ' , (r at: 'selector') asString , '\n' , '--- removing\n' , (r at: 'old_source') , '\n'
					]
					ifFalse: [
						kind = 'set_class_header' ifTrue: [
								result:: result , '\n--- old header\n' , (r at: 'old_source') , '\n' , '+++ new header\n' , (r at: 'source') , '\n'
							]
							ifFalse: [
								kind = 'delete_nested_class' ifTrue: [
										result:: result , '\n--- removing class\n' , (r at: 'old_source') , '\n'
									]
									ifFalse: [
										
										(* add_or_replace_method, add_or_replace_lazy_slot,
					   add_or_replace_nested_class, add_top_level_class *)
										result:: result , '\n+++ new source\n' , (r at: 'source') , '\n'
									]
							]
					]
			].
		result:: result , '\nWhen the user approves, call apply_changeset with id "' , id , '".'.
		^result
	)
	intermediateOf: builder = (
		(* Reach into a {Class,Mixin}Builder's private 'intermediate' slot.
	   AtomicInstallWrapper>>install:into: uses the same trick. *)
		
		^((ObjectMirror reflecting: builder) getSlot: #intermediate) reflectee
	)
	patchEnclosingOf: childClassBuilder withParent: parentClassBuilder = (
		(* When we navigate DOWN from a top-level builder into
	   instanceSide.nestedClasses, the nested IR's enclosingClass is the
	   parent IntermediateClassDeclaration (set in buildIntermediate:from:within:).
	   But ClassDeclarationBuilder>>enclosingClass expects an IntermediateMixin
	   (the parent's instance-side mixin) — see the patch at line 572 of
	   MirrorsForPrimordialSoup.ns, which only runs on the mirror-up path.
	   Mirror that patch here so the compiler can walk the scope chain. *)
		
		| childIR parentInstanceSideIR |
		childIR:: intermediateOf: childClassBuilder.
		parentInstanceSideIR:: intermediateOf: parentClassBuilder instanceSide.
		childIR enclosingClass: parentInstanceSideIR
	)
	navigateToBuilderForSegments: segments <Array> withBuilderMap: builderByTopLevel ^<Object> = (
		(* Resolve a dotted class path (given as segments) to a ClassDeclarationBuilder.
	   For top-level segments, fetch or create the cached top-level builder.
	   For nested segments, walk DOWN inside it, patching enclosingClass linkages
	   as we go (see patchEnclosingOf:withParent: for why). *)
		
		| topName targetClassBuilder |
		topName:: segments at: 1.
		targetClassBuilder:: builderByTopLevel at: topName
			ifAbsent: [
				| topCdm topBuilder |
				topCdm:: classDeclarationNamed: topName.
				topBuilder:: topCdm asBuilder.
				builderByTopLevel at: topName put: topBuilder.
				topBuilder
			].
		2 to: segments size
			do: [:i |
				| seg found |
				seg:: segments at: i.
				found:: nil.
				targetClassBuilder instanceSide nestedClasses do: [:ncBuilder |
						ncBuilder name = seg ifTrue: [ found:: ncBuilder ]
					].
				found isNil ifTrue: [
						Error signal: 'Nested class not found in builder tree: ' , seg , ' (under ' , topName , ')'
					].
				patchEnclosingOf: found withParent: targetClassBuilder.
				targetClassBuilder:: found
			].
		^targetClassBuilder
	)
	applyOneRecord: r withBuilderMap: builderByTopLevel = (
		| kind segments targetClassBuilder side mixinBuilder |
		kind:: r at: 'kind'.
		kind = 'add_top_level_class' ifTrue: [
				| newBuilder name |
				newBuilder:: ClassDeclarationBuilder fromSource: (r at: 'source').
				name:: newBuilder name asSymbol.
				(builderByTopLevel includesKey: name) ifTrue: [
						Error signal: 'Top-level builder for ' , name , ' already present in this changeset (duplicate add or conflict)'
					].
				builderByTopLevel at: name put: newBuilder.
				^self
			].
		kind = 'delete_nested_class' ifTrue: [
				| parentBuilder targetName |
				segments:: (r at: 'class_name') findTokens: '.'.
				parentBuilder:: navigateToBuilderForSegments: (segments copyFrom: 1
						to: segments size - 1)
					withBuilderMap: builderByTopLevel.
				targetName:: (segments at: segments size) asSymbol.
				parentBuilder instanceSide nestedClasses removeMirrorNamed: targetName.
				^self
			].
		
		(* All remaining kinds operate on a target class identified by class_name. *)
		segments:: (r at: 'class_name') findTokens: '.'.
		targetClassBuilder:: navigateToBuilderForSegments: segments
			withBuilderMap: builderByTopLevel.
		kind = 'set_class_header' ifTrue: [
				^targetClassBuilder header source: (r at: 'source')
			].
		kind = 'add_or_replace_nested_class' ifTrue: [
				^targetClassBuilder instanceSide nestedClasses addFromSource: (r at: 'source')
			].
		
		(* Member-level kinds: route through instance or class side. *)
		side:: r at: 'side'.
		mixinBuilder:: side = 'class' ifTrue: [ targetClassBuilder classSide ]
			ifFalse: [ targetClassBuilder instanceSide ].
		kind = 'add_or_replace_method' ifTrue: [
				^mixinBuilder methods addFromSource: (r at: 'source')
			].
		kind = 'delete_method' ifTrue: [
				^mixinBuilder methods removeMirrorNamed: (r at: 'selector')
			].
		kind = 'add_or_replace_lazy_slot' ifTrue: [
				^mixinBuilder lazySlots addFromSource: (r at: 'source')
			].
		kind = 'delete_lazy_slot' ifTrue: [
				^mixinBuilder lazySlots removeMirrorNamed: (r at: 'selector')
			].
		Error signal: 'Unknown change kind in apply: ' , kind
	)
	applyChangesetRecords: records = (
		(* Aggregates changes per top-level class and installs them as one
	   atomic transaction via the platform's atomic installer. *)
		
		| builderByTopLevel builders newTopLevelNames mixins |
		builderByTopLevel:: Map new.
		newTopLevelNames:: List new.
		records do: [:r |
				(r at: 'kind') = 'add_top_level_class' ifTrue: [
						newTopLevelNames add: (r at: 'class_name')
					].
				applyOneRecord: r withBuilderMap: builderByTopLevel
			].
		builders:: List new.
		builderByTopLevel keysAndValuesDo: [:k :v | builders add: v ].
		mixins:: ide installFromBuilders: builders.
		
		(* The atomic installer returns mirrors but does NOT add new top-level
	   classes to the IDE namespace on primordialsoup (the JS mirror builders
	   do; the wasm ones don't). Mirror the IDE's own post-install step. *)
		mixins do: [:m |
				(newTopLevelNames includes: m name) ifTrue: [
						Root at: m name asSymbol put: m declaration applyToObject reflectee
					]
			]
	)
	simulateRecordsAsChangeset: records <List> ^<Map> = (
		(* Build a Changeset Map (the shape consumed by ChangesetPresenter)
	   that describes what `applyChangesetRecords: records` would do
	   against the live namespace, *without* installing anything.

	   Strategy: start from each touched top-level class's live snapshot
	   (or an empty snapshot for an add_top_level_class record), then
	   apply each record's effect at the snapshot level (mutating the
	   methods / classMethods / lazySlots / nestedClasses / header
	   sub-maps directly). Finally diff each proposed snapshot against
	   the live snapshot and classify as #new / #changed.

	   We do not pretend to handle every corner case the full atomic
	   installer covers (e.g. an add_top_level_class whose name already
	   exists raises in the installer; here we simply mark the class as
	   #changed). The presenter's role is to show the user what will
	   change; the actual install path still validates. *)
		
		| snapsByTop newClasses sourcesByTop classDiffs |
		snapsByTop:: Map new.
		newClasses:: Set new.
		sourcesByTop:: Map new.
		records do: [:r |
				seedSnapshotForRecord: r
					snapsByTop: snapsByTop
					newClasses: newClasses
					sourcesByTop: sourcesByTop
			].
		records do: [:r | applyRecordToSnapshot: r in: snapsByTop ].
		classDiffs:: Map new.
		snapsByTop keysAndValuesDo: [:topName :proposedSnap |
				| liveCls |
				(newClasses includes: topName) ifTrue: [
						classDiffs at: topName
							put: (Map new at: #status put: #new;
								at: #liveSnapshot put: proposedSnap;
								at: #liveSource put: (sourcesByTop at: topName ifAbsent: [ nil ]);
								yourself)
					]
					ifFalse: [
						liveCls:: Root at: topName ifAbsent: [ nil ].
						liveCls isNil ifFalse: [
								| liveSnap diff |
								liveSnap:: repositories liveSnapshotOf: liveCls.
								diff:: repositories diffSnapshot: liveSnap to: proposedSnap.
								(repositories diffIsEmpty: diff) ifFalse: [
										| headSrc |
										headSrc:: [ (classDeclarationNamed: topName asString) source ] on: Exception
											do: [:e | nil ].
										classDiffs at: topName
											put: (Map new at: #status put: #changed;
												at: #diff put: diff;
												at: #headSnapshot put: liveSnap;
												at: #liveSnapshot put: proposedSnap;
												at: #headSource put: headSrc;
												yourself)
									]
							]
					]
			].
		^Map new at: #classDiffs put: classDiffs;
			at: #skipped put: List new;
			yourself
	)
	seedSnapshotForRecord: r <Map> snapsByTop: snapsByTop <Map> newClasses: newClasses <Set> sourcesByTop: sourcesByTop <Map> = (
		(* Make sure snapsByTop has an entry for the top-level class touched
	   by record r. add_top_level_class seeds from the record's full
	   source; everything else seeds from the live namespace if the class
	   exists. Records touching an unknown live class are silently
	   skipped at this stage — the corresponding entry simply won't make
	   it into classDiffs. *)
		
		| kind topName liveCls |
		kind:: r at: 'kind'.
		kind = 'add_top_level_class' ifTrue: [
				| src |
				topName:: (r at: 'class_name') asSymbol.
				src:: r at: 'source'.
				newClasses add: topName.
				sourcesByTop at: topName put: src.
				(snapsByTop includesKey: topName) ifFalse: [
						snapsByTop at: topName
							put: (repositories extractedSnapshotFromSource: src)
					].
				^self
			].
		topName:: ((r at: 'class_name') findTokens: '.') at: 1.
		topName:: topName asSymbol.
		(snapsByTop includesKey: topName) ifTrue: [ ^self ].
		liveCls:: Root at: topName ifAbsent: [ nil ].
		liveCls isNil ifFalse: [
				snapsByTop at: topName put: (repositories liveSnapshotOf: liveCls)
			]
	)
	applyRecordToSnapshot: r <Map> in: snapsByTop <Map> = (
		(* Mutate the proposed snapshot for the top-level class of record r
	   to reflect r's effect. Walks down nested classes by dotted name.
	   No-op if the relevant top-level snapshot isn't present (record
	   was orphaned in seedSnapshotForRecord:). *)
		
		| kind segments topName snap target side membersKey |
		kind:: r at: 'kind'.
		kind = 'add_top_level_class' ifTrue: [ ^self ].
		segments:: (r at: 'class_name') findTokens: '.'.
		topName:: (segments at: 1) asSymbol.
		snap:: snapsByTop at: topName ifAbsent: [ ^self ].
		target:: snap.
		2 to: segments size
			do: [:i |
				| seg nested |
				seg:: (segments at: i) asSymbol.
				nested:: (target at: #nestedClasses) at: seg ifAbsent: [ nil ].
				nested isNil ifTrue: [ ^self ].
				target:: nested
			].
		kind = 'set_class_header' ifTrue: [
				target at: #header put: (r at: 'source').
				^self
			].
		kind = 'add_or_replace_nested_class' ifTrue: [
				| newSnap nestedName |
				
				(* Nested source is a bare nested-class declaration, not a top-level
		   unit — must be snapshotted via the nested-install parse path, not
		   extractedSnapshotFromSource: (which expects the 'Newspeak'/'Root'
		   unit header and would fail the changeset render). *)
				newSnap:: repositories extractedSnapshotFromNestedSource: (r at: 'source').
				nestedName:: (newSnap at: #name) asSymbol.
				(target at: #nestedClasses) at: nestedName put: newSnap.
				^self
			].
		kind = 'delete_nested_class' ifTrue: [
				| parent nestedName |
				
				(* class_name is the nested class to remove; segments[1..n-1] is
		   the parent path. Re-walk to the parent. *)
				parent:: snap.
				2 to: segments size - 1
					do: [:i |
						| seg nested |
						seg:: (segments at: i) asSymbol.
						nested:: (parent at: #nestedClasses) at: seg ifAbsent: [ nil ].
						nested isNil ifTrue: [ ^self ].
						parent:: nested
					].
				nestedName:: (segments at: segments size) asSymbol.
				(parent at: #nestedClasses) removeKey: nestedName ifAbsent: [ ].
				^self
			].
		side:: (r includesKey: 'side') ifTrue: [ r at: 'side' ]
			ifFalse: [ 'instance' ].
		(kind = 'add_or_replace_lazy_slot' or: [ kind = 'delete_lazy_slot' ]) ifTrue: [
				membersKey:: #lazySlots
			]
			ifFalse: [
				(kind = 'add_or_replace_method' or: [ kind = 'delete_method' ]) ifTrue: [
						membersKey:: side = 'class' ifTrue: [ #classMethods ]
							ifFalse: [ #methods ]
					]
					ifFalse: [ ^self ]
			].
		kind = 'add_or_replace_method' ifTrue: [
				| selName |
				selName:: extractMethodSelectorFromSource: (r at: 'source').
				(target at: membersKey) at: selName put: (r at: 'source').
				^self
			].
		kind = 'add_or_replace_lazy_slot' ifTrue: [
				| selName |
				selName:: extractLazySlotSelectorFromSource: (r at: 'source').
				(target at: membersKey) at: selName put: (r at: 'source').
				^self
			].
		
		(* delete_method / delete_lazy_slot *)
		(target at: membersKey) removeKey: (r at: 'selector') asSymbol ifAbsent: [ ]
	)
	extractMethodSelectorFromSource: src <String> ^<Symbol> = (
		(* Parse via a throwaway builder. The real installer uses the same
	   addFromSource: API, which returns a mirror with a `name`. We use
	   that name as the snapshot key. *)
		
		| tmp m |
		tmp:: ClassDeclarationBuilder fromSource: 'class NewspeakSelectorProbe = () ()'.
		m:: tmp instanceSide methods addFromSource: src.
		^m name
	)
	extractLazySlotSelectorFromSource: src <String> ^<Symbol> = (
		| tmp s |
		tmp:: ClassDeclarationBuilder fromSource: 'class NewspeakSelectorProbe = () ()'.
		s:: tmp instanceSide lazySlots addFromSource: src.
		^s name
	)
	aiWorkspaceSubject ^<Object> = (
		(* Get-or-create the AI workspace via the WorkspaceManager's standard
	   API. The workspace state (the workspaces list, counters) is in the
	   WorkspaceManager module instance; the methods that manipulate it
	   (addWorkspace, getWorkspace:, ...) are on the nested
	   AllWorkspacesSubject class, accessing module state via lexical
	   scope. Browsing.ns uses the same idiom — create a fresh
	   AllWorkspacesSubject and call getWorkspace: on it; all subject
	   instances share the same enclosing workspaces list, so the lookup-
	   or-create is global to the IDE session.
	   The resulting workspace is registered in the manager's list and
	   inherits Workspace's platform/ide/Root bindings. Cached so its
	   evaluator (which owns the visible-in-UI results list) is the same
	   one each call. *)
		
		aiWorkspaceSubject_slot isNil ifFalse: [ ^aiWorkspaceSubject_slot ].
		aiWorkspaceSubject_slot:: ide theWorkspaceManager AllWorkspacesSubject new getWorkspace: 'AIWorkspace'.
		objectRegistry at: 'workspace' put: aiWorkspaceSubject_slot objectMirror.
		^aiWorkspaceSubject_slot
	)
	aiWorkspaceMirror ^<Object> = (
		^aiWorkspaceSubject objectMirror
	)
	registerResult: aMirror <Object> withName: nameOrNil <String | Nil> ^<String> = (
		| id |
		(nameOrNil isNil or: [ nameOrNil isEmpty ]) ifTrue: [
				nextResultIdNum:: nextResultIdNum + 1.
				id:: 'r' , nextResultIdNum printString
			]
			ifFalse: [ id:: nameOrNil ].
		objectRegistry at: id put: aMirror.
		^id
	)
	registerActivation: anActivationMirror <Object> ^<String> = (
		(* Register an ActivationMirror under an 'aN' id, deduping against
	   already-registered activations (ActivationMirror>>= compares
	   underlying activation identity, so the same frame stays under one
	   id no matter how many times it's reached). *)
		
		| id |
		objectRegistry keysAndValuesDo: [:k :v |
				((k size > 0 and: [ (k at: 1) = 'a' first ]) and: [ v = anActivationMirror ]) ifTrue: [
						^k
					]
			].
		nextActivationIdNum:: nextActivationIdNum + 1.
		id:: 'a' , nextActivationIdNum printString.
		objectRegistry at: id put: anActivationMirror.
		^id
	)
	activationForId: id <String> ^<Object> = (
		| m |
		m:: mirrorForObjectId: id.
		m isKindOfActivationMirror ifFalse: [
				Error signal: 'Object [' , id , '] is not an activation frame'
			].
		^m
	)
	isPrimitiveResult: aMirror <Object> ^<Boolean> = (
		(* Primitives (Integer, Float, String, Symbol, Boolean, Character, nil)
	   are NOT registered — the AI can use their printString directly. *)
		
		| r |
		r:: aMirror reflectee.
		r isNil ifTrue: [ ^true ].
		r isKindOfInteger ifTrue: [ ^true ].
		r isKindOfFloat ifTrue: [ ^true ].
		r isKindOfString ifTrue: [ ^true ].
		r isKindOfSymbol ifTrue: [ ^true ].
		r isKindOfBoolean ifTrue: [ ^true ].
		r isKindOfCharacter ifTrue: [ ^true ].
		^false
	)
	summaryOf: aMirror <Object> ^<String> = (
		| className printStr |
		className:: [ aMirror getClass mixin name asString ] on: Error
			do: [:e | '(class?)' ].
		printStr:: [ aMirror reflectee printString ] on: Error
			do: [:e | '(printString raised: ' , e messageText , ')' ].
		printStr size > 200 ifTrue: [
				printStr:: (printStr copyFrom: 1 to: 197) , '...'
			].
		^className , ': ' , printStr
	)
	mirrorForObjectId: id <String> ^<Object> = (
		id = 'workspace' ifTrue: [ ^aiWorkspaceMirror ].
		id = 'focus' ifTrue: [
				
				(* Resolves dynamically to whichever evaluator the user has focused
		   on, so the AI never has to track a stale id between turns. *)
				focusKind = #evaluator ifFalse: [
						Error signal: 'No evaluator focus is set. Click a brain on a workspace, ' , 'object inspector, method evaluator, or debugger activation, ' , 'or pass in_id: "workspace" to use the AI workspace.'
					].
				^focusEvaluatorMirror_slot
			].
		^objectRegistry at: id
			ifAbsent: [
				Error signal: 'No such object id: ' , id , '. Use list_objects to see registered ids.'
			]
	)
	toolsWithFocus: focus <ChatFocus> ^<List> = (
		(* The full IDE tool catalogue handed to every Session built through
	   this module. Each tool's individual factory below carries its own
	   description, JSON-Schema, and handler closure; this list just
	   composes them. Grouped roughly by area: code introspection,
	   document/amplet manipulation, navigation, testing, atomic
	   changesets, evaluation/inspection, and debugger control. *)
		
		^{getClassSourceTool. getMemberSourceTool. getClassHeaderTool. listClassMembersTool. sendersTool. implementorsTool. searchClassesTool. listNamespaceTool. getDocumentTool. createDocumentTool. createChatDocumentTool. setDocumentContentsTool. deleteDocumentTool. listAmpletsTool. addAmpletTool. setAmpletExpressionTool. deleteAmpletTool. listMediaTool. deleteMediaTool. webFetchTool. (currentFocusToolForFocus: focus). navigateToClassTool. navigateToNamespaceTool. navigateToDocumentTool. showTestsTool. runTestsTool. getTestResultsTool. getTestFailureDetailsTool. runFailingTestsTool. runErroringTestsTool. runOneTestTool. (proposeChangesToolForFocus: focus). (applyChangesetToolForFocus: focus). evaluateTool. navigateToObjectTool. inspectObjectTool. listObjectsTool. forgetObjectTool. getCurrentFrameTool. getStackTraceTool. getCurrentExpressionTool. inspectActivationTool. stepTool. returnFromTool. continueThreadTool. }
	)
	public toolsForProvider: provider <Provider> ^<List[Tool]> = (
		(* tools plus any capability-gated extras the given provider can drive.
	   uploadFileTool delivers content as an array of text/image/document
	   blocks in tool_result.content; only providers whose
	   supportsFileUploads is true get it offered. *)
		
		^toolsForProvider: provider focus: (ChatFocus onDoc: nil)
	)
	public toolsForProvider: provider <Provider> focus: focus <ChatFocus> ^<List[Tool]> = (
		(* As toolsForProvider:, but the current_focus tool reports `focus` — the
	   per-chat focus owned by the session's chat — so concurrent sessions don't
	   share focus (M2a). *)

		| result <List[Tool]> |
		result:: List new.
		(toolsWithFocus: focus) do: [:t <Tool> | result add: t ].
		provider supportsFileUploads ifTrue: [ result add: uploadFileTool ].
		^result
	)
	getClassSourceTool ^<Tool> = (
		^Tool name: 'get_class_source'
			description: 'Get the full source code of a Newspeak class. Use a dotted path for nested classes (e.g. "ShapeLibrary.Circle").'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Class name or dotted path (e.g. MyClass or Outer.Inner)"}},"required":["class_name"]}'
			handler: [:input | (resolveClassPath: (input at: 'class_name')) source ]
	)
	getClassHeaderTool ^<Tool> = (
		^Tool name: 'get_class_header'
			description: 'Get just the class header (factory method signature, superclass clause, slot declarations) without the method bodies.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| cdm historicalMatch |
				cdm:: resolveClassPath: (input at: 'class_name').
				historicalMatch:: focusSha_slot isNil not and: [
						focusKind = #classHeader and: [ focusClassPath = (qualifiedNameOf: cdm) ]
					].
				historicalMatch ifTrue: [ focusHistoricalSource_slot ]
					ifFalse: [ cdm header source ]
			]
	)
	listClassMembersTool ^<Tool> = (
		^Tool name: 'list_class_members'
			description: 'List all members (methods, slots, nested classes, lazy slots) of a class with their access modifiers. Does not include source code - use get_member_source for that.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| cdm result |
				cdm:: resolveClassPath: (input at: 'class_name').
				result:: 'Class: ' , cdm simpleName , '\n'.
				result:: result , 'Factory: ' , cdm primaryFactorySelector , '\n'.
				result:: result , '\nSlots:\n'.
				cdm instanceSide slots do: [:sm |
						result:: result , '  ' , (formatAccess: sm accessModifier) , sm name , (sm isMutable ifTrue: [
								' (mutable)'
							]
							ifFalse: [ ' (immutable)' ]) , '\n'
					].
				result:: result , '\nInstance methods:\n'.
				cdm instanceSide methods do: [:mm |
						result:: result , '  ' , (formatAccess: mm accessModifier) , mm name , '\n'
					].
				cdm instanceSide lazySlots do: [:ls |
						result:: result , '  ' , (formatAccess: ls accessModifier) , 'lazy ' , ls name , '\n'
					].
				result:: result , '\nClass methods:\n'.
				cdm classSide methods do: [:mm |
						result:: result , '  ' , (formatAccess: mm accessModifier) , mm name , '\n'
					].
				result:: result , '\nNested classes:\n'.
				cdm instanceSide nestedClasses do: [:nc |
						result:: result , '  ' , (formatAccess: nc accessModifier) , nc simpleName , '\n'
					].
				result
			]
	)
	sendersTool ^<Tool> = (
		^Tool name: 'senders_of'
			description: 'Find all methods that send a given message selector. Returns the defining class and method for each sender.'
			inputSchema: '{"type":"object","properties":{"selector":{"type":"string","description":"The message selector to search for (e.g. add:, printString, +)"}},"required":["selector"]}'
			handler: [:input |
				| selector result count |
				selector:: (input at: 'selector') asSymbol.
				result:: 'Senders of #' , selector , ':\n'.
				count:: 0.
				systemScope sendersOf: selector
					do: [:mirror |
						count:: count + 1.
						mirror isKindOfMethodMirror ifTrue: [
								result:: result , '  ' , (qualifiedNameOf: mirror definingMixin declaration) , ' >> ' , mirror name , '\n'
							]
							ifFalse: [
								mirror isKindOfLazySlotMirror ifTrue: [
										result:: result , '  ' , (qualifiedNameOf: mirror definingMixin declaration) , ' >> ' , mirror name , ' (lazy slot)\n'
									]
									ifFalse: [
										mirror isKindOfClassDeclarationMirror ifTrue: [
												result:: result , '  ' , (qualifiedNameOf: mirror) , ' (class header)\n'
											]
									]
							]
					].
				count = 0 ifTrue: [ result:: result , '  (none found)\n' ].
				result
			]
	)
	implementorsTool ^<Tool> = (
		^Tool name: 'implementors_of'
			description: 'Find all classes that implement a given message selector. Returns the defining class and access modifier for each implementor.'
			inputSchema: '{"type":"object","properties":{"selector":{"type":"string","description":"The message selector to search for"}},"required":["selector"]}'
			handler: [:input |
				| selector result count |
				selector:: (input at: 'selector') asSymbol.
				result:: 'Implementors of #' , selector , ':\n'.
				count:: 0.
				systemScope implementorsOf: selector
					do: [:mirror |
						count:: count + 1.
						mirror isKindOfLazySlotMirror ifTrue: [
								result:: result , '  ' , (formatAccess: mirror accessModifier) , (qualifiedNameOf: mirror definingMixin declaration) , ' >> ' , mirror name , ' (lazy slot)\n'
							].
						mirror isKindOfMethodMirror ifTrue: [
								result:: result , '  ' , (formatAccess: mirror accessModifier) , (qualifiedNameOf: mirror definingMixin declaration) , ' >> ' , mirror name , '\n'
							].
						mirror isKindOfClassDeclarationMirror ifTrue: [
								result:: result , '  ' , (qualifiedNameOf: mirror) , ' (class/slot)\n'
							]
					].
				count = 0 ifTrue: [ result:: result , '  (none found)\n' ].
				result
			]
	)
	listNamespaceTool ^<Tool> = (
		^Tool name: 'list_namespace'
			description: 'List the entries of a Newspeak namespace. With no argument (or an empty path), lists the IDE Root namespace. Use a dotted path to drill into a nested namespace (e.g. "Icons" or "Root.Icons"). Each entry is reported as "name (kind)" where kind is one of: namespace, class, document, string, image, alien, other.'
			inputSchema: '{"type":"object","properties":{"path":{"type":"string","description":"Optional dotted path to a namespace. Empty or omitted means Root."}}}'
			handler: [:input |
				| path ns label result |
				
				(* input is a JS Alien — use includesKey: rather than at:ifAbsent:,
			   which the alien does not understand. *)
				path:: (input includesKey: 'path') ifTrue: [ input at: 'path' ]
					ifFalse: [ '' ].
				ns:: resolveNamespacePath: path.
				label:: path isEmpty ifTrue: [ 'Root' ] ifFalse: [ path ].
				result:: 'Namespace ' , label , ':\n'.
				ns keysAndValuesDo: [:k :v |
						result:: result , '  ' , k , ' (' , (kindOf: v) , ')\n'
					].
				result
			]
	)
	currentFocusToolForFocus: focus <ChatFocus> ^<Tool> = (
		^Tool name: 'current_focus'
			description: 'Return a description of the current IDE context. Two parts, concatenated: (a) "Active chat document: X. " — the ChatDocument hosting this conversation, when one is active (omitted otherwise); (b) the brain-button focus the user has pointed at — class, method, namespace, document, evaluator — or "(no focus set)" if none. The two are orthogonal: the user can be in chat doc Foo while asking about method Bar by clicking its brain. Call this first whenever the user refers to "this", "here", or names a member without a class.'
			inputSchema: '{"type":"object","properties":{}}'
			handler: [:input | focus description ]
	)
	webFetchTool ^<Tool> = (
		^Tool name: 'web_fetch'
			description: 'Fetch a URL and return its response body as text. Useful for consulting the published Newspeak language specification and grammar (https://newspeaklanguage.org/spec/newspeak-spec.tex) or the tutorial (https://newspeaklanguage.org/pubs/newspeak-2025-tutorial.pdf), and for other web lookups. The response is returned as a single string; for binary content (PDFs, images) the text decoding may be lossy.'
			inputSchema: '{"type":"object","properties":{"url":{"type":"string","description":"Absolute URL to fetch (https:// or http://)."}},"required":["url"]}'
			handler: [:input | aiAccess webFetch: (input at: 'url') ]
	)
	pickFile ^<Alien[Promise]> = (
		(* Open the OS file picker via Hopscotch's FileChooserFragment. Resolves
	   to the chosen Alien[File] on selection; rejects with a string if the
	   user dismisses the dialog. The fragment is constructed fresh per call;
	   a hidden <input> is built lazily on its first input access, so we
	   don't need to insert anything into the DOM.

	   Implementation note: built on Promise.withResolvers() rather than
	   `new Promise(executor)`. Primordialsoup's alien bridge does NOT pass
	   arguments to a Newspeak closure invoked synchronously by the
	   Promise constructor — both `resolve` and `reject` arrive as nil —
	   so the executor pattern is unusable. withResolvers exposes the
	   resolve/reject as ordinary JS function aliens, which we invoke
	   later (asynchronously, from event handlers) via Function.call. *)
		
		| deferred <Alien> resolveFn <Alien> rejectFn <Alien> |
		deferred:: aiAccess JSPromise withResolvers.
		resolveFn:: deferred at: 'resolve'.
		rejectFn:: deferred at: 'reject'.
		FileChooserFragment new chooseSingleFile: [:file <Alien> |
				resolveFn call: js undefined with: file.
				nil
			]
			ifCanceled: [
				rejectFn call: js undefined with: 'File selection canceled'.
				nil
			].
		^deferred at: 'promise'
	)
	readFileAsBase64: file <Alien> ^<Alien[Promise]> = (
		(* Read the file's bytes via FileReader.readAsDataURL and resolve to the
	   base64 payload (the part after 'data:<mime>;base64,'). Used for
	   binary uploads — images and PDFs — that must be transported as
	   base64 inside Anthropic content blocks. Uses Promise.withResolvers()
	   for the same reason pickFile does — see its comment. *)
		
		| FileReader <Alien> reader <Alien> deferred <Alien> resolveFn <Alien> rejectFn <Alien> |
		FileReader:: aiAccess global at: 'FileReader'.
		reader:: FileReader new.
		deferred:: aiAccess JSPromise withResolvers.
		resolveFn:: deferred at: 'resolve'.
		rejectFn:: deferred at: 'reject'.
		reader addEventListener: 'load'
			action: [:event |
				| dataUrl <String> commaIdx <Integer> |
				dataUrl:: reader at: 'result'.
				commaIdx:: dataUrl indexOf: ','.
				commaIdx = 0 ifTrue: [
						rejectFn call: js undefined
							with: 'FileReader returned no data: URL prefix'
					]
					ifFalse: [
						resolveFn call: js undefined
							with: (dataUrl copyFrom: commaIdx + 1 to: dataUrl size)
					].
				nil
			].
		reader addEventListener: 'error'
			action: [:event |
				rejectFn call: js undefined with: 'FileReader error'.
				nil
			].
		reader readAsDataURL: file.
		^deferred at: 'promise'
	)
	isBinaryMime: mime <String> ^<Boolean> = (
		(* Known binary MIME categories we deliver as media attachments. Everything
	   else (text/*, application/json/xml/javascript, application/octet-stream,
	   empty/unknown) falls through to the text-decoding path. SVG (image/
	   svg+xml) is text-shaped but still goes through the image media path
	   because providers that accept image/* take SVG verbatim. *)
		
		mime = 'application/pdf' ifTrue: [ ^true ].
		(mime startsWith: 'image/') ifTrue: [ ^true ].
		(mime startsWith: 'audio/') ifTrue: [ ^true ].
		(mime startsWith: 'video/') ifTrue: [ ^true ].
		^false
	)
	toolResultText: text <String> ^<Alien> = (
		(* Canonical {text, media: []} JS object for a text-only result. *)
		
		| result emptyMedia |
		emptyMedia:: aiAccess JSON parse: '[]'.
		result:: aiAccess JSON parse: '{}'.
		result at: 'text' put: text.
		result at: 'media' put: emptyMedia.
		^result
	)
	toolResultMediaB64: b64 <String> mime: mime <String> name: name <String> ^<Alien> = (
		(* Canonical {text, media: [{mimeType, dataBase64, name}]} JS object for
	   a single media attachment. The text field announces the attachment so
	   the model has a textual reference; the provider's makeToolResult:
	   may further augment it (e.g. Gemini appends 'Attached files: …'). *)
		
		| result media part text |
		text:: name isEmpty ifTrue: [ 'Attached file (' , mime , ')' ]
			ifFalse: [ 'Attached: ' , name ].
		part:: aiAccess JSON parse: '{}'.
		part at: 'mimeType' put: mime.
		part at: 'dataBase64' put: b64.
		name isEmpty ifFalse: [ part at: 'name' put: name ].
		media:: aiAccess JSON parse: '[]'.
		media push: part.
		result:: aiAccess JSON parse: '{}'.
		result at: 'text' put: text.
		result at: 'media' put: media.
		^result
	)
	fileToToolResult: file <Alien> ^<Alien[Promise]> = (
		(* Resolves to the canonical {text, media} JS object the upload_file tool
	   hands back to Session. Binary files — image/*, application/pdf,
	   audio/*, video/* — are read as base64 and packaged as a single media
	   attachment; everything else is decoded as text and returned as the
	   text field with a filename prefix. The provider's makeToolResult:
	   then translates this canonical form into its native shape — and
	   drops any media MIME it can't carry, with a note in the text. *)
		
		| mime name |
		
		(* JS undefined doesn't satisfy isNil; the ", ''" pattern coerces a real
	   String through and raises on anything else (undefined, null, numbers). *)
		mime:: [ (file at: 'type') , '' ] on: Exception do: [:e | '' ].
		name:: [ (file at: 'name') , '' ] on: Exception do: [:e | '' ].
		(isBinaryMime: mime) ifTrue: [
				^(readFileAsBase64: file) then: [:b64 <String> |
						toolResultMediaB64: b64 mime: mime name: name
					]
			].
		^file text then: [:text <String> |
				| body |
				body:: name isEmpty ifTrue: [ text ]
					ifFalse: [ name , String lf , String lf , text ].
				toolResultText: body
			]
	)
	uploadFileTool ^<Tool> = (
		^Tool name: 'upload_file'
			description: 'Ask the user to upload a file from their local filesystem. Opens an OS file picker; the user selects one file and the tool returns its contents. Text files (text/*, JSON, XML, source code, etc.) are decoded and returned as text. Binary files — images, PDFs, audio, and video — are returned as media attachments; provider support for each media type varies, and the tool result will note any attachment your model cannot see. Use this when you need the user to share a file you cannot otherwise read (e.g., a local source file outside the IDE namespace, a configuration file, a log, a screenshot, a PDF). The tool errors with "File selection canceled" if the user dismisses the picker.'
			inputSchema: '{"type":"object","properties":{},"required":[]}'
			handler: [:input | pickFile then: [:file <Alien> | fileToToolResult: file ] ]
	)
	parentNamespaceAndLeaf: dottedPath <String> ^<Object> = (
		(* Walk the path segments to the parent namespace; return a 2-tuple
	   {parentNamespace. leafName}. Used by create/delete to locate the
	   container of the entry being added/removed. Raises if any
	   intermediate segment isn't found or isn't a namespace. *)
		
		| parts current i leaf |
		parts:: dottedPath findTokens: '.'.
		parts isEmpty ifTrue: [ Error signal: 'Empty path' ].
		leaf:: parts at: parts size.
		current:: Root.
		i:: 1.
		(parts isEmpty not and: [ (parts at: 1) = 'Root' ]) ifTrue: [ i:: 2 ].
		[ i < parts size ] whileTrue: [
				| seg = parts at: i. |
				current:: current at: seg asSymbol
					ifAbsent: [ Error signal: 'Namespace segment not found: ' , seg ].
				current isKindOfNamespace ifFalse: [
						Error signal: 'Path segment is not a namespace: ' , seg
					].
				i:: i + 1
			].
		^{current. leaf. }
	)
	documentAt: dottedPath <String> ^<Object> = (
		| entry |
		entry:: resolveNamespacePath: dottedPath.
		entry isKindOfDocument ifFalse: [
				Error signal: 'Not a document: ' , dottedPath , ' (it is a ' , (kindOf: entry) , ')'
			].
		^entry
	)
	parseAmpletContainer: html <String> ^<Object> = (
		| jsDoc div |
		jsDoc:: js global at: 'document'.
		div:: jsDoc createElement: 'div'.
		div at: 'innerHTML' put: html.
		^div
	)
	findAmpletWithId: id <String> in: container <Object> ^<Object> = (
		| amplets count i |
		amplets:: container getElementsByClassName: 'ampleforth'.
		count:: amplets at: 'length'.
		i:: 0.
		[ i < count ] whileTrue: [
				| amplet thisId |
				amplet:: amplets at: i.
				thisId:: amplet getAttribute: 'ampletId'.
				thisId = id ifTrue: [ ^amplet ].
				i:: i + 1
			].
		Error signal: 'No amplet with ampletId="' , id , '" in this document'
	)
	createChatDocumentTool ^<Tool> = (
		^Tool name: 'create_chat_document'
			description: 'Create a new ChatDocument at the given dotted path. The path''s parent must be an existing namespace. A ChatDocument hosts one AI conversation; opening it shows a live chat UI bound to its provider + model. The API key is read from localStorage per provider — it is NOT stored on the document. Supported provider values: "anthropic", "gemini" (gemini is text-only smoke-test wiring; tool calls not yet supported). This is a programmatic entry point; the user-facing path is the chat setup screen.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Dotted path for the new chat document"},"model_name":{"type":"string","description":"Model name (e.g. \"claude-sonnet-4-6\" for anthropic, \"gemini-1.5-pro-latest\" for gemini)"},"provider":{"type":"string","description":"Provider key: \"anthropic\" or \"gemini\". Optional; defaults to \"anthropic\"."}},"required":["name","model_name"]}'
			handler: [:input |
				| name pair parent leaf doc provider |
				name:: input at: 'name'.
				pair:: parentNamespaceAndLeaf: name.
				parent:: pair at: 1.
				leaf:: pair at: 2.
				(parent includesKey: leaf asSymbol) ifTrue: [
						Error signal: 'An entry named ' , leaf , ' already exists at this path'
					].
				provider:: (input includesKey: 'provider') ifTrue: [ input at: 'provider' ]
					ifFalse: [ 'anthropic' ].
				doc:: createChatNamed: leaf
					provider: provider
					model: (input at: 'model_name').
				parent at: leaf asSymbol put: doc.
				ide browsing updateCurrentDisplay.
				'Created chat document ' , name
			]
	)
	createDocumentTool ^<Tool> = (
		^Tool name: 'create_document'
			description: 'Create a new Ampleforth document at the given dotted path. The path''s parent must be an existing namespace (e.g. just "MyNotes" puts it in Root; "Foo.Bar.Notes" puts Notes in Root.Foo.Bar). Optional initial_contents is the document''s starting HTML; if omitted, the document is created with the default blank template. Fails if any entry already exists at that path.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Dotted path for the new document"},"initial_contents":{"type":"string","description":"Optional initial HTML"}},"required":["name"]}'
			handler: [:input |
				| name pair parent leaf doc initial |
				name:: input at: 'name'.
				pair:: parentNamespaceAndLeaf: name.
				parent:: pair at: 1.
				leaf:: pair at: 2.
				(parent includesKey: leaf asSymbol) ifTrue: [
						Error signal: 'An entry named ' , leaf , ' already exists at this path'
					].
				initial:: (input includesKey: 'initial_contents') ifTrue: [
						input at: 'initial_contents'
					]
					ifFalse: [ nil ].
				doc:: initial isNil ifTrue: [
						ide documents freshDocumentNamed: leaf asSymbol
					]
					ifFalse: [
						ide documents freshDocumentNamed: leaf asSymbol initialText: initial
					].
				parent at: leaf asSymbol put: doc.
				ide browsing updateCurrentDisplay.
				'Created document ' , name
			]
	)
	setDocumentContentsTool ^<Tool> = (
		^Tool name: 'set_document_contents'
			description: 'Replace the HTML contents of an existing Ampleforth document. The previous contents are lost — describe the change to the user before calling. Use get_document first if you need to know the current state.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"},"contents":{"type":"string","description":"New HTML contents"}},"required":["name","contents"]}'
			handler: [:input |
				| name doc |
				name:: input at: 'name'.
				doc:: documentAt: name.
				doc mutateContentsTo: (input at: 'contents').
				ide browsing updateCurrentDisplay.
				'Updated contents of ' , name
			]
	)
	deleteDocumentTool ^<Tool> = (
		^Tool name: 'delete_document'
			description: 'Remove an Ampleforth document from its namespace. Destructive; describe the action to the user first.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"}},"required":["name"]}'
			handler: [:input |
				| name pair parent leaf entry |
				name:: input at: 'name'.
				pair:: parentNamespaceAndLeaf: name.
				parent:: pair at: 1.
				leaf:: pair at: 2.
				entry:: parent at: leaf asSymbol
					ifAbsent: [ Error signal: 'No such entry: ' , name ].
				entry isKindOfDocument ifFalse: [
						Error signal: name , ' is a ' , (kindOf: entry) , ', not a document; refusing to delete via this tool.'
					].
				parent removeKey: leaf asSymbol.
				ide browsing updateCurrentDisplay.
				'Deleted document ' , name
			]
	)
	listAmpletsTool ^<Tool> = (
		^Tool name: 'list_amplets'
			description: 'List the amplets in a document. Each amplet is reported as a fenced block: a header line "=== [INDEX] ampletId=ID ===" followed by the amplet''s Newspeak expression. The ampletId is stable within an editing session but gets renumbered when the document is reloaded from disk — do not assume ids persist across sessions.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"}},"required":["name"]}'
			handler: [:input |
				| name doc container amplets count i result |
				name:: input at: 'name'.
				doc:: documentAt: name.
				container:: parseAmpletContainer: doc contents.
				amplets:: container getElementsByClassName: 'ampleforth'.
				count:: amplets at: 'length'.
				count = 0 ifTrue: [ 'No amplets in ' , name ]
					ifFalse: [
						result:: 'Amplets in ' , name , ' (' , count printString , '):\n'.
						i:: 0.
						[ i < count ] whileTrue: [
								| amplet aid expr |
								amplet:: amplets at: i.
								aid:: amplet getAttribute: 'ampletId'.
								aid isNil ifTrue: [ aid:: '?' ].
								expr:: amplet getAttribute: 'name'.
								expr isNil ifTrue: [ expr:: '' ].
								result:: result , '=== [' , i printString , '] ampletId=' , aid , ' ===\n' , expr , '\n'.
								i:: i + 1
							].
						result
					]
			]
	)
	addAmpletTool ^<Tool> = (
		^Tool name: 'add_amplet'
			description: 'Append a new amplet to a document. The amplet''s expression (the "name" attribute) is the supplied Newspeak expression, evaluated against the host Document when the document renders. A fresh ampletId is allocated automatically. Returns the new ampletId. Destructive — describe the change to the user before calling. v1 always appends at the end; targeted placement will come later.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"},"expression":{"type":"string","description":"Newspeak expression for the amplet (the name attribute)"}},"required":["name","expression"]}'
			handler: [:input |
				| name expr doc container newId jsDoc newAmplet body bodies thinking |
				name:: input at: 'name'.
				expr:: input at: 'expression'.
				doc:: documentAt: name.
				container:: parseAmpletContainer: doc contents.
				
				(* The document body lives inside a wrapping <div class="self_ampleforth">
			   (the editable "blue box"); insert new amplets there so they land
			   inside the document boundary, not as a sibling of the wrapper. Fall
			   back to the container if no such wrapper is present. *)
				bodies:: container getElementsByClassName: 'self_ampleforth'.
				body:: (bodies at: 'length') > 0 ifTrue: [ bodies at: 0 ]
					ifFalse: [ container ].
				newId:: doc nextAmpletId printString.
				jsDoc:: js global at: 'document'.
				newAmplet:: jsDoc createElement: 'div'.
				newAmplet setAttribute: 'class' to: 'ampleforth'.
				newAmplet setAttribute: 'ampletId' to: newId.
				newAmplet setAttribute: 'name' to: expr.
				newAmplet setAttribute: 'contenteditable' to: 'false'.
				
				(* For ChatDocuments, place the amplet just before the
			   thinkingOrModelPicker amplet so chat controls stay anchored at
			   the bottom. For regular docs, append at the end of the wrapper. *)
				thinking:: doc isKindOfChatDocument ifTrue: [
						findChatStructuralAmplet: 'thinkingOrModelPicker' in: container
					]
					ifFalse: [ nil ].
				thinking isNil ifTrue: [ body appendChild: newAmplet ]
					ifFalse: [
						(thinking at: 'parentNode') insertBefore: newAmplet before: thinking
					].
				doc mutateContentsTo: (container at: 'innerHTML').
				ide browsing updateCurrentDisplay.
				'Added amplet to ' , name , ' (ampletId=' , newId , ')'
			]
	)
	setAmpletExpressionTool ^<Tool> = (
		^Tool name: 'set_amplet_expression'
			description: 'Change the Newspeak expression of an existing amplet, identified by ampletId. Destructive — describe the change to the user before calling.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"},"amplet_id":{"type":"string","description":"The ampletId of the amplet to modify (from list_amplets)"},"expression":{"type":"string","description":"New Newspeak expression for the name attribute"}},"required":["name","amplet_id","expression"]}'
			handler: [:input |
				| name aid expr doc container amplet |
				name:: input at: 'name'.
				aid:: input at: 'amplet_id'.
				expr:: input at: 'expression'.
				doc:: documentAt: name.
				container:: parseAmpletContainer: doc contents.
				amplet:: findAmpletWithId: aid in: container.
				amplet setAttribute: 'name' to: expr.
				doc mutateContentsTo: (container at: 'innerHTML').
				ide browsing updateCurrentDisplay.
				'Updated amplet ' , aid , ' in ' , name
			]
	)
	deleteAmpletTool ^<Tool> = (
		^Tool name: 'delete_amplet'
			description: 'Remove an amplet from a document, identified by ampletId. Destructive — describe the change to the user before calling.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"},"amplet_id":{"type":"string","description":"The ampletId of the amplet to delete (from list_amplets)"}},"required":["name","amplet_id"]}'
			handler: [:input |
				| name aid doc container amplet parent |
				name:: input at: 'name'.
				aid:: input at: 'amplet_id'.
				doc:: documentAt: name.
				container:: parseAmpletContainer: doc contents.
				amplet:: findAmpletWithId: aid in: container.
				parent:: amplet at: 'parentNode'.
				parent removeChild: amplet.
				doc mutateContentsTo: (container at: 'innerHTML').
				ide browsing updateCurrentDisplay.
				'Deleted amplet ' , aid , ' from ' , name
			]
	)
	listMediaTool ^<Tool> = (
		^Tool name: 'list_media'
			description: 'List the media entries (images, audio, video blobs) attached to a document. Returns one line per entry with its path, MIME type, and size in bytes.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"}},"required":["name"]}'
			handler: [:input |
				| name doc reg result |
				name:: input at: 'name'.
				doc:: documentAt: name.
				reg:: doc mediaRegistry.
				reg isEmpty ifTrue: [ 'No media in ' , name ]
					ifFalse: [
						result:: 'Media in ' , name , ' (' , reg size printString , '):\n'.
						reg keysAndValuesDo: [:path :blob |
								| mime |
								mime:: blob at: 'type'.
								mime isNil ifTrue: [ mime:: '?' ].
								result:: result , '  ' , path , '  type=' , mime , '  size=' , (blob at: 'size') printString , '\n'
							].
						result
					]
			]
	)
	deleteMediaTool ^<Tool> = (
		^Tool name: 'delete_media'
			description: 'Remove a media entry from a document''s media registry, identified by its path. Destructive — describe the change to the user first. If the document''s HTML or any amplet expression references this path, those references will dangle.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"},"path":{"type":"string","description":"The media path (from list_media)"}},"required":["name","path"]}'
			handler: [:input |
				| name path doc reg |
				name:: input at: 'name'.
				path:: input at: 'path'.
				doc:: documentAt: name.
				reg:: doc mediaRegistry.
				(reg includesKey: path) ifFalse: [
						Error signal: 'No media entry "' , path , '" in ' , name
					].
				reg removeKey: path.
				ide browsing updateCurrentDisplay.
				'Deleted media ' , path , ' from ' , name
			]
	)
	getDocumentTool ^<Tool> = (
		^Tool name: 'get_document'
			description: 'Get the textual contents of an IDE document (e.g. a literate/Ampleforth document stored in a namespace). Specify the document name or a dotted path to its location in the namespace tree.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path (e.g. \"MyNotes\")."}},"required":["name"]}'
			handler: [:input |
				| path entry |
				path:: input at: 'name'.
				entry:: resolveNamespacePath: path.
				entry isKindOfDocument ifFalse: [
						Error signal: 'Not a document: ' , path , ' (it is a ' , (kindOf: entry) , ')'
					].
				entry contents
			]
	)
	searchClassesTool ^<Tool> = (
		^Tool name: 'search_classes'
			description: 'Search for classes whose name contains the given substring. Searches both top-level and nested classes.'
			inputSchema: '{"type":"object","properties":{"query":{"type":"string","description":"Substring to search for in class names (case-sensitive)"}},"required":["query"]}'
			handler: [:input |
				| query result count |
				query:: input at: 'query'.
				result:: 'Classes matching "' , query , '":\n'.
				count:: 0.
				systemScope allClassesDo: [:cdm |
						(cdm simpleName includesSubstring: query) ifTrue: [
								count:: count + 1.
								result:: result , '  ' , (formatAccess: cdm accessModifier) , (qualifiedNameOf: cdm) , '\n'
							]
					].
				count = 0 ifTrue: [ result:: result , '  (none found)\n' ].
				result
			]
	)
	navigateToClassTool ^<Tool> = (
		^Tool name: 'navigate_to_class'
			description: 'Navigate the IDE to a class, opening a class presenter on it. Use a dotted path for nested classes (e.g. "ShapeLibrary.Circle"). Side effect: the IDE jumps; use only when the user has expressed intent to navigate.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| cdm |
				cdm:: resolveClassPath: (input at: 'class_name').
				ide browsing navigateTo: (ide browsing ClassSubject onDeclaration: cdm).
				'Opened class ' , (qualifiedNameOf: cdm)
			]
	)
	navigateToNamespaceTool ^<Tool> = (
		^Tool name: 'navigate_to_namespace'
			description: 'Navigate the IDE to a namespace, opening a namespace presenter. With no argument (or empty path), opens Root. Use a dotted path for nested namespaces (e.g. "Icons" or "Root.Icons"). Side effect: the IDE jumps.'
			inputSchema: '{"type":"object","properties":{"path":{"type":"string","description":"Optional dotted path. Empty or omitted means Root."}}}'
			handler: [:input |
				| path subject |
				path:: (input includesKey: 'path') ifTrue: [ input at: 'path' ]
					ifFalse: [ '' ].
				subject:: namespaceSubjectForPath: path.
				ide browsing navigateTo: subject.
				'Opened namespace ' , subject title
			]
	)
	navigateToDocumentTool ^<Tool> = (
		^Tool name: 'navigate_to_document'
			description: 'Navigate the IDE to an Ampleforth document by name or dotted path. Side effect: the IDE jumps.'
			inputSchema: '{"type":"object","properties":{"name":{"type":"string","description":"Document name or dotted path"}},"required":["name"]}'
			handler: [:input |
				| path entry |
				path:: input at: 'name'.
				entry:: resolveNamespacePath: path.
				entry isKindOfDocument ifFalse: [
						Error signal: 'Not a document: ' , path , ' (it is a ' , (kindOf: entry) , ')'
					].
				ide browsing navigateTo: (ide documents DocumentSubject onModel: entry).
				'Opened document ' , path
			]
	)
	showTestsTool ^<Tool> = (
		^Tool name: 'show_tests'
			description: 'Open the test-suite view for a test configuration class — equivalent to clicking the [show tests] link on a test configuration''s class entry. Pass the test configuration class''s dotted path. This does not run the suite.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Test configuration class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| cdm classSubject |
				cdm:: resolveClassPath: (input at: 'class_name').
				classSubject:: ide browsing ClassSubject onDeclaration: cdm.
				classSubject isTestConfiguration ifFalse: [
						Error signal: (qualifiedNameOf: cdm) , ' is not a test configuration class'
					].
				ide browsing navigateTo: classSubject inactiveTestingSubject.
				'Opened test suite for ' , (qualifiedNameOf: cdm)
			]
	)
	runTestsTool ^<Tool> = (
		^Tool name: 'run_tests'
			description: 'Run the test suite for a test configuration class — equivalent to clicking the [run tests] link on a test configuration''s class entry. The IDE jumps to the in-progress test view; if the test runner raises, the IDE navigates to a debugging thread subject instead. Pass the test configuration class''s dotted path.

The Tester instance is captured for subsequent calls to get_test_results, run_failing_tests, run_erroring_tests, and run_test.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Test configuration class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| cdm classSubject testSubject thread |
				cdm:: resolveClassPath: (input at: 'class_name').
				classSubject:: ide browsing ClassSubject onDeclaration: cdm.
				classSubject isTestConfiguration ifFalse: [
						Error signal: (qualifiedNameOf: cdm) , ' is not a test configuration class'
					].
				testSubject:: classSubject testingSubject.
				testersByConfigName at: cdm simpleName asString put: testSubject.
				thread:: ActivationMirror invokeSuspended: [
						ide browsing navigateTo: testSubject
					].
				thread resume.
				thread isFulfilled ifFalse: [
						ide browsing navigateTo: (ide debugging ThreadSubject onModel: thread)
					].
				'Running tests for ' , (qualifiedNameOf: cdm) , '. Use get_test_results to retrieve outcomes when complete.'
			]
	)
	testerForConfigPath: configClassPath <String> ^<Object> = (
		| cdm testSubject |
		cdm:: resolveClassPath: configClassPath.
		testSubject:: testersByConfigName at: cdm simpleName asString
			ifAbsent: [
				Error signal: 'No test run cached for ' , configClassPath , '. Call run_tests first.'
			].
		^testSubject tester
	)
	testCaseId: testCase <Object> ^<String> = (
		^testCase environment name asString , ' >> ' , testCase selector asString
	)
	findTestCase: testName <String> inTester: tester <Object> ^<Object> = (
		| all match |
		all:: List new.
		tester errors do: [:r | all add: r testCase ].
		tester failures do: [:r | all add: r testCase ].
		tester successes do: [:r | all add: r testCase ].
		tester inactive do: [:tc | all add: tc ].
		match:: all detect: [:tc | (testCaseId: tc) = testName ] ifNone: [ nil ].
		match isNil ifTrue: [
				Error signal: 'No test named "' , testName , '" in this config''s suite.'
			].
		^match
	)
	summarizeFailure: r <Object> ^<String> = (
		^[ r description ] on: Error do: [:e | '(no description)' ]
	)
	summarizeError: r <Object> ^<String> = (
		^[ r exception class name asString , ': ' , r exception messageText ] on: Error
			do: [:e | '(unprintable exception)' ]
	)
	formatTestSummary: tester <Object> configPath: configPath <String> ^<String> = (
		| sb total complete ratio |
		total:: [ tester testCaseList size ] on: Error do: [:e | 0 ].
		complete:: tester errors size + tester failures size + tester successes size.
		ratio:: total = 0 ifTrue: [ 1.0 ] ifFalse: [ complete asFloat / total ].
		sb:: 'Test config: ' , configPath , '\n'.
		sb:: sb , 'Status: ' , complete printString , ' of ' , total printString , ' tests complete (' , (ratio * 100) rounded printString , '%)\n'.
		sb:: sb , '  Passed:   ' , tester successes size printString , '\n'.
		sb:: sb , '  Failed:   ' , tester failures size printString , '\n'.
		sb:: sb , '  Errored:  ' , tester errors size printString , '\n'.
		sb:: sb , '  Disabled: ' , tester disabled size printString , '\n'.
		sb:: sb , '  Inactive: ' , tester inactive size printString , ' (not yet run or not part of last selection)\n'.
		tester failures isEmpty ifFalse: [
				sb:: sb , '\nFailures:\n'.
				tester failures do: [:r |
						sb:: sb , '  [' , (testCaseId: r testCase) , '] ' , (summarizeFailure: r) , '\n'
					]
			].
		tester errors isEmpty ifFalse: [
				sb:: sb , '\nErrors:\n'.
				tester errors do: [:r |
						sb:: sb , '  [' , (testCaseId: r testCase) , '] ' , (summarizeError: r) , '\n'
					]
			].
		complete < total ifTrue: [
				sb:: sb , '\n(Tests may still be running; call get_test_results again later for an updated snapshot.)\n'
			].
		^sb
	)
	getTestResultsTool ^<Tool> = (
		^Tool name: 'get_test_results'
			description: 'Retrieve outcomes from the most recent run_tests (or selective re-run) for a test configuration class. Returns counts of passed / failed / errored / disabled / inactive plus one-line summaries of each failure and error. Use get_test_failure_details for full info on a specific test.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Test configuration class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| configPath tester |
				configPath:: input at: 'class_name'.
				tester:: testerForConfigPath: configPath.
				formatTestSummary: tester configPath: configPath
			]
	)
	getTestFailureDetailsTool ^<Tool> = (
		^Tool name: 'get_test_failure_details'
			description: 'Get full detail on a single failure or error from the most recent test run. test_name is the id formatted as "ContextName >> test_selector" — exactly as it appears in get_test_results.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Test configuration class name or dotted path"},"test_name":{"type":"string","description":"ContextName >> test_selector form"}},"required":["class_name","test_name"]}'
			handler: [:input |
				| configPath testName tester testCase failureResult errorResult successResult result |
				configPath:: input at: 'class_name'.
				testName:: input at: 'test_name'.
				tester:: testerForConfigPath: configPath.
				testCase:: findTestCase: testName inTester: tester.
				failureResult:: tester failures detect: [:r | r testCase = testCase ]
					ifNone: [ nil ].
				errorResult:: tester errors detect: [:r | r testCase = testCase ]
					ifNone: [ nil ].
				successResult:: tester successes detect: [:r | r testCase = testCase ]
					ifNone: [ nil ].
				failureResult isNil ifFalse: [
						^'[' , testName , '] FAILURE\nDescription: ' , (summarizeFailure: failureResult)
					].
				errorResult isNil ifFalse: [
						^'[' , testName , '] ERROR\n' , 'Exception class: ' , ([
							errorResult exception class name asString
						] on: Error do: [:e | '(unknown)' ]) , '\n' , 'Message: ' , ([
							errorResult exception messageText
						] on: Error do: [:e | '(unprintable)' ]) , '\n' , '(For full stack, navigate to the testing view and click the test in the IDE.)'
					].
				successResult isNil ifFalse: [
						^'[' , testName , '] PASSED — no failure detail to report.'
					].
				'[' , testName , '] is inactive — not run in the latest invocation.'
			]
	)
	runTestsForCases: testCases <Object> tester: tester <Object> = (
		(* Run each test case in turn through tester run:, which mutates the
	   tester''s errors / failures / successes lists. Iterate over a copy
	   because run: removes-then-adds. *)
		
		(testCases copyFrom: 1 to: testCases size) do: [:tc |
				[ tester run: tc ] on: Error do: [:e | ]
			]
	)
	runFailingTestsTool ^<Tool> = (
		^Tool name: 'run_failing_tests'
			description: 'Re-run only the failing tests from the most recent run. Updates the cached Tester in place. The IDE testing view (if currently displayed) refreshes to show the new state.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Test configuration class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| configPath tester count |
				configPath:: input at: 'class_name'.
				tester:: testerForConfigPath: configPath.
				count:: tester failures size.
				runTestsForCases: (tester failures collect: [:r | r testCase ])
					tester: tester.
				ide browsing updateCurrentDisplay.
				'Re-ran ' , count printString , ' failing test' , (count = 1 ifTrue: [ '' ]
					ifFalse: [ 's' ]) , '. Call get_test_results for the new outcome.'
			]
	)
	runErroringTestsTool ^<Tool> = (
		^Tool name: 'run_erroring_tests'
			description: 'Re-run only the erroring tests from the most recent run. Updates the cached Tester in place. The IDE testing view (if currently displayed) refreshes to show the new state.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Test configuration class name or dotted path"}},"required":["class_name"]}'
			handler: [:input |
				| configPath tester count |
				configPath:: input at: 'class_name'.
				tester:: testerForConfigPath: configPath.
				count:: tester errors size.
				runTestsForCases: (tester errors collect: [:r | r testCase ]) tester: tester.
				ide browsing updateCurrentDisplay.
				'Re-ran ' , count printString , ' erroring test' , (count = 1 ifTrue: [ '' ]
					ifFalse: [ 's' ]) , '. Call get_test_results for the new outcome.'
			]
	)
	runOneTestTool ^<Tool> = (
		^Tool name: 'run_test'
			description: 'Re-run a single test by name. test_name is the "ContextName >> test_selector" form as it appears in get_test_results. The cached Tester is updated in place and the IDE testing view refreshes.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Test configuration class name or dotted path"},"test_name":{"type":"string","description":"ContextName >> test_selector form"}},"required":["class_name","test_name"]}'
			handler: [:input |
				| configPath testName tester testCase |
				configPath:: input at: 'class_name'.
				testName:: input at: 'test_name'.
				tester:: testerForConfigPath: configPath.
				testCase:: findTestCase: testName inTester: tester.
				[ tester run: testCase ] on: Error
					do: [:e | Error signal: 'Re-run failed: ' , e messageText ].
				ide browsing updateCurrentDisplay.
				'Re-ran [' , testName , ']. Call get_test_results for the new outcome.'
			]
	)
	proposeChangesToolForFocus: focus <ChatFocus> ^<Tool> = (
		^Tool name: 'propose_changes'
			description: 'Stage a set of code edits for atomic installation. Does NOT install. Returns a short summary plus a changeset id; the IDE renders the proposal as a structured diff inline in the chat. Wait for explicit user approval ("apply", "ok", "go ahead") before calling apply_changeset — or, if the user clicks the inline Apply button themselves, you will see a follow-up assistant note saying the changeset was applied. If the user wants something different, refine the changes and call propose_changes again.

Each entry in the changes array is one of:
- {kind: "add_or_replace_method",       class_name, side?, source}
- {kind: "delete_method",               class_name, side?, selector}
- {kind: "add_or_replace_lazy_slot",    class_name, side?, source}
- {kind: "delete_lazy_slot",            class_name, side?, selector}
- {kind: "set_class_header",            class_name, source}
- {kind: "add_or_replace_nested_class", class_name, source}  -- class_name is the ENCLOSING class
- {kind: "delete_nested_class",         class_name}          -- class_name is the nested class to remove
- {kind: "add_top_level_class",         class_name, source}  -- class_name must match the simpleName in source

class_name is a dotted path; side defaults to "instance" for member ops. source is full Newspeak source. Multiple changes in one call install atomically — use this for mutually dependent edits.

Top-level class DELETION is not supported by this tool (different mechanism, not part of atomic install). Renaming a class is not supported either; set_class_header preserves the simple name.'
			inputSchema: '{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["add_or_replace_method","delete_method","add_or_replace_lazy_slot","delete_lazy_slot","set_class_header","add_or_replace_nested_class","delete_nested_class","add_top_level_class"]},"class_name":{"type":"string"},"side":{"type":"string","enum":["instance","class"]},"selector":{"type":"string"},"source":{"type":"string"}},"required":["kind","class_name"]}}},"required":["changes"]}'
			handler: [:input |
				| changes records id |
				changes:: input at: 'changes'.
				records:: List new.
				
				(* changes is a JS array, not a Newspeak Collection; iterate by index. *)
				0 to: (changes at: 'length') - 1
					do: [:i | records add: (validateChange: (changes at: i)) ].
				records isEmpty ifTrue: [ Error signal: 'No changes provided' ].
				id:: freshChangesetId.
				proposedChangesets at: id put: records.
				enqueuePendingChangesetId: id forChat: (proposingChatFor: focus).
				summarizeChangesetId: id records: records
			]
	)
	applyChangesetToolForFocus: focus <ChatFocus> ^<Tool> = (
		^Tool name: 'apply_changeset'
			description: 'Atomically install a previously proposed changeset. Call this only after the user has reviewed the diff returned by propose_changes and explicitly approved. On success returns "Applied changeset <id>". On failure the atomic install rolls back, so no partial state is left in the running system.'
			inputSchema: '{"type":"object","properties":{"id":{"type":"string","description":"The changeset id returned by propose_changes"}},"required":["id"]}'
			handler: [:input |
				| id records |
				id:: input at: 'id'.
				records:: proposedChangesets at: id
					ifAbsent: [
						Error signal: 'No such changeset: ' , id , ' (already applied, discarded, or never proposed)'
					].
				applyChangesetRecords: records.
				proposedChangesets removeKey: id.
				(* M3: notify the OTHER open chats; this session is the applier. *)
				broadcastChangeAppliedBy: (proposingChatFor: focus) records: records.
				'Applied changeset ' , id
			]
	)
	evaluateTool ^<Tool> = (
		^Tool name: 'evaluate'
			description: 'Evaluate a Newspeak expression. By default the receiver is the AI workspace (id "workspace") — a regular IDE workspace named AIWorkspace, with platform, ide, and Root accessible via the Workspace superclass. Pass in_id to evaluate with a previously registered object as the receiver.

Non-primitive results are registered in the object registry under an auto-generated id (e.g. "r3") or your chosen name (via the name parameter). Primitives (Integer, Float, String, Symbol, Boolean, Character, nil) are NOT registered — their printString is just returned.

Side-effecting expressions (collection mutations, slot assignments via setters, etc.) are allowed — this is the REPL primitive. Use propose_changes / apply_changeset for code installation, not raw evaluate.'
			inputSchema: '{"type":"object","properties":{"expression":{"type":"string","description":"Newspeak expression to evaluate"},"in_id":{"type":"string","description":"Id of registered receiver (default: workspace)"},"name":{"type":"string","description":"Optional friendly id for the result, instead of auto-generated rN"}},"required":["expression"]}'
			handler: [:input |
				| exprSource inId nameOrNil receiver thread resultMirror |
				exprSource:: input at: 'expression'.
				inId:: (input includesKey: 'in_id') ifTrue: [ input at: 'in_id' ]
					ifFalse: [
						
						(* Default to whatever evaluator the user has focused on
					   (workspace, object inspector, method evaluator,
					   debugger activation). Falls through to the AI
					   workspace when no evaluator focus is set. *)
						focusKind = #evaluator ifTrue: [ 'focus' ] ifFalse: [ 'workspace' ]
					].
				nameOrNil:: (input includesKey: 'name') ifTrue: [ input at: 'name' ]
					ifFalse: [ nil ].
				receiver:: mirrorForObjectId: inId.
				thread:: [ receiver evaluate: exprSource ] on: Error
					do: [:e | Error signal: 'Evaluation failed at compile: ' , e messageText ].
				
				(* When evaluating against an in-IDE evaluator (the workspace via
			   id 'workspace', or whatever the user has focused on via
			   id 'focus'), append the ThreadMirror to that evaluator's
			   results list so the result becomes visible in the IDE — both
			   live (we trigger updateCurrentDisplay) and on later
			   navigation. For arbitrary objects from the registry, there
			   is no associated presenter to update; the AI sees the result
			   via its returned id and tools, which is enough for v1.
			   All best-effort — never let an exposure failure mask the
			   actual evaluation result. *)
				inId = 'workspace' ifTrue: [
						[ aiWorkspaceSubject evaluator results add: thread ] on: Error do: [:e | ].
						ide browsing updateCurrentDisplay
					]
					ifFalse: [
						inId = 'focus' ifTrue: [
								focusEvaluatorSubject_slot isNil ifFalse: [
										[ focusEvaluatorSubject_slot results add: thread ] on: Error
											do: [:e | ]
									].
								ide browsing updateCurrentDisplay
							]
					].
				thread isBroken ifTrue: [
						| ex topFrame frameId frameNote |
						ex:: [ thread result reflectee printString ] on: Error
							do: [:e | '(broken; unprintable)' ].
						
						(* Register the top stack frame so the AI can immediately
				   inspect the failure. *)
						topFrame:: [ thread suspendedActivation ] on: Error do: [:e | nil ].
						frameId:: topFrame isNil ifTrue: [ nil ]
							ifFalse: [ registerActivation: topFrame ].
						frameNote:: frameId isNil ifTrue: [ '' ]
							ifFalse: [
								' Top frame registered as ' , frameId , '; use get_stack_trace to inspect.'
							].
						Error signal: 'Evaluation raised at runtime: ' , ex , '.' , frameNote
					].
				resultMirror:: thread result.
				
				(* Use ifTrue:ifFalse: rather than ^early-return: this is a stored
			   handler block whose enclosing method (evaluateTool) has already
			   returned, so ^ would raise CannotReturn. *)
				(isPrimitiveResult: resultMirror) ifTrue: [
						'=> ' , (summaryOf: resultMirror)
					]
					ifFalse: [
						| id |
						id:: registerResult: resultMirror withName: nameOrNil.
						'=> [' , id , '] ' , (summaryOf: resultMirror)
					]
			]
	)
	navigateToObjectTool ^<Tool> = (
		^Tool name: 'navigate_to_object'
			description: 'Navigate the IDE to an object presenter on a registered object. Pass the id from evaluate or list_objects. Side effect: the IDE jumps.'
			inputSchema: '{"type":"object","properties":{"id":{"type":"string","description":"Registered object id (e.g. r1, or workspace)"}},"required":["id"]}'
			handler: [:input |
				| id mirror |
				id:: input at: 'id'.
				mirror:: mirrorForObjectId: id.
				ide browsing navigateTo: (ide browsing ObjectSubject onModel: mirror).
				'Opened object [' , id , '] ' , (summaryOf: mirror)
			]
	)
	inspectObjectTool ^<Tool> = (
		^Tool name: 'inspect_object'
			description: 'Get a short summary of a registered object — class name and printString. To enumerate the messages it responds to, follow up with list_class_members on the class.'
			inputSchema: '{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}'
			handler: [:input |
				| id mirror |
				id:: input at: 'id'.
				mirror:: mirrorForObjectId: id.
				'Object [' , id , ']\nClass: ' , mirror getClass mixin name asString , '\nprintString: ' , ([
					mirror reflectee printString
				] on: Error do: [:e | '(raised: ' , e messageText , ')' ])
			]
	)
	listObjectsTool ^<Tool> = (
		^Tool name: 'list_objects'
			description: 'List all objects registered in the AI object registry, with their ids and summaries. Includes the always-present workspace.'
			inputSchema: '{"type":"object","properties":{}}'
			handler: [:input |
				| result |
				
				(* Ensure workspace is registered. *)
				aiWorkspaceMirror.
				result:: 'Registered objects:\n'.
				objectRegistry keysAndValuesDo: [:id :m |
						result:: result , '  [' , id , '] ' , (summaryOf: m) , '\n'
					].
				result
			]
	)
	formatMethodNameOf: anActivationMirror ^<String> = (
		(* Best-effort "Class >> selector" for a frame. *)
		
		^[
			| m mixinDecl |
			m:: anActivationMirror method.
			mixinDecl:: m definingMixin declaration.
			(qualifiedNameOf: mixinDecl) , ' >> ' , m name asString
		] on: Exception do: [:e | '(unknown method)' ]
	)
	formatActivationLine: anActivationMirror id: id ^<String> = (
		^'[' , id , '] ' , (formatMethodNameOf: anActivationMirror)
	)
	formatSourceWithRange: source <String> range: rangeOrNil <Object> ^<String> = (
		(* Append a structured marker for the active range rather than splicing
	   into the source text — easier for the AI to read at a glance. *)
		
		| header |
		header:: rangeOrNil isNil ifTrue: [ 'active: (no range info)' ]
			ifFalse: [
				'active: source positions ' , rangeOrNil start printString , '..' , rangeOrNil stop printString
			].
		^header , String lf , '---' , String lf , source
	)
	getCurrentFrameTool ^<Tool> = (
		^Tool name: 'get_current_frame'
			description: 'Return the registered activation id of the currently-focused debugger frame / method evaluator / lazy-slot evaluator. Raises if no activation focus is set. Use this to bootstrap into get_stack_trace, inspect_activation, etc. from a user-driven debug session.'
			inputSchema: '{"type":"object","properties":{}}'
			handler: [:input |
				(focusKind = #evaluator and: [
						focusEvaluatorMirror_slot isNil not and: [
								focusEvaluatorMirror_slot isKindOfActivationMirror
							]
					]) ifTrue: [
						| id |
						id:: registerActivation: focusEvaluatorMirror_slot.
						'Current frame: ' , (formatActivationLine: focusEvaluatorMirror_slot
							id: id)
					]
					ifFalse: [
						Error signal: 'No activation is currently focused. Click a brain on a debugger frame, method evaluator, or lazy-slot evaluator first.'
					]
			]
	)
	getStackTraceTool ^<Tool> = (
		^Tool name: 'get_stack_trace'
			description: 'Walk the call stack starting at the given activation, going down through callers via sender. Each frame is (re)registered under its aN id so you can evaluate(in_id: "aN"), inspect_activation(id: "aN"), etc. Pass either the activation id from get_current_frame or the id returned in a broken-evaluate error message.'
			inputSchema: '{"type":"object","properties":{"activation_id":{"type":"string","description":"Registered activation id (e.g. a1)"}},"required":["activation_id"]}'
			handler: [:input |
				| startId start result frame depth |
				startId:: input at: 'activation_id'.
				start:: activationForId: startId.
				result:: 'Stack from [' , startId , '] downward:' , String lf.
				frame:: start.
				depth:: 0.
				[ frame isNil ] whileFalse: [
						| id |
						id:: registerActivation: frame.
						result:: result , '  ' , depth printString , '. ' , (formatActivationLine: frame
							id: id) , String lf.
						frame:: [ frame sender ] on: Error do: [:e | nil ].
						depth:: depth + 1
					].
				result
			]
	)
	getCurrentExpressionTool ^<Tool> = (
		^Tool name: 'get_current_expression'
			description: 'Return the method source for an activation, with a structured marker giving the source positions of the currently-executing (or paused) expression. Format is: a header line ("active: source positions N..M"), a separator, then the method source verbatim. The N..M positions index into the source string (1-based inclusive of start, exclusive of stop).'
			inputSchema: '{"type":"object","properties":{"activation_id":{"type":"string"}},"required":["activation_id"]}'
			handler: [:input |
				| id activation source range |
				id:: input at: 'activation_id'.
				activation:: activationForId: id.
				source:: [ activation method source ] on: Exception
					do: [:e | '(source unavailable)' ].
				range:: [ activation sourceRange ] on: Exception do: [:e | nil ].
				'Frame [' , id , '] ' , (formatMethodNameOf: activation) , String lf , (formatSourceWithRange: source
					range: range)
			]
	)
	threadStateName: thread ^<String> = (
		[ thread isFulfilled ifTrue: [ ^'fulfilled' ] ] on: Exception do: [:e | ].
		[ thread isBroken ifTrue: [ ^'broken' ] ] on: Exception do: [:e | ].
		[ thread isSuspended ifTrue: [ ^'suspended' ] ] on: Exception do: [:e | ].
		[ thread isTerminated ifTrue: [ ^'terminated' ] ] on: Exception do: [:e | ].
		^'unknown'
	)
	pruneDeadActivations = (
		(* Remove from the registry any aN that points at an activation that
	   is no longer continuable (frame has unwound or thread fulfilled). *)
		
		| dead |
		dead:: List new.
		objectRegistry keysAndValuesDo: [:k :v |
				(((k size > 0 and: [ (k at: 1) = 'a' first ]) and: [
						v isKindOfActivationMirror
					]) and: [ [ v isUncontinuable ] on: Exception do: [:e | true ] ]) ifTrue: [
						dead add: k
					]
			].
		dead do: [:k | objectRegistry removeKey: k ]
	)
	postOperationReport: thread ^<String> = (
		(* Called after any step/return: report the new thread state, register
	   the result if fulfilled, register the new top frame if still suspended,
	   prune dead activation ids, and clear focus if it pointed at a frame
	   that's gone. Returns a human-readable status fragment. *)
		
		| status |
		status:: 'thread state: ' , (threadStateName: thread).
		([ thread isFulfilled ] on: Exception do: [:e | false ]) ifTrue: [
				| result resultId |
				result:: [ thread result ] on: Exception do: [:e | nil ].
				result isNil ifFalse: [
						resultId:: registerResult: result withName: nil.
						status:: status , '; result registered as ' , resultId
					]
			].
		([ thread isSuspended ] on: Exception do: [:e | false ]) ifTrue: [
				| topFrame topId |
				topFrame:: [ thread suspendedActivation ] on: Exception do: [:e | nil ].
				topFrame isNil ifFalse: [
						topId:: registerActivation: topFrame.
						status:: status , '; top frame now [' , topId , '] ' , (formatMethodNameOf: topFrame)
					]
			].
		pruneDeadActivations.
		(focusKind = #evaluator and: [
				focusEvaluatorMirror_slot isNil not and: [
						focusEvaluatorMirror_slot isKindOfActivationMirror and: [
								[ focusEvaluatorMirror_slot isUncontinuable ] on: Exception
									do: [:e | true ]
							]
					]
			]) ifTrue: [ clearFocus ].
		^status
	)
	stepTool ^<Tool> = (
		^Tool name: 'step'
			description: 'Step the thread at a given activation frame. kind is one of: into (step into the next call), over (step over it), out (run until this frame returns), through (step into closure), restart (re-execute this frame from its first statement). After the step, the report names the new top frame if the thread is still suspended; registers the result and reports it if the thread fulfills; cleans up activations that are no longer reachable. The IDE debugger view is refreshed.'
			inputSchema: '{"type":"object","properties":{"activation_id":{"type":"string"},"kind":{"type":"string","enum":["into","over","out","through","restart"]}},"required":["activation_id","kind"]}'
			handler: [:input |
				| id kind activation newThread |
				id:: input at: 'activation_id'.
				kind:: input at: 'kind'.
				activation:: activationForId: id.
				newThread:: nil.
				kind = 'into' ifTrue: [ newThread:: activation stepInto ].
				kind = 'over' ifTrue: [ newThread:: activation stepOver ].
				kind = 'out' ifTrue: [ newThread:: activation stepOut ].
				kind = 'through' ifTrue: [ newThread:: activation stepThrough ].
				kind = 'restart' ifTrue: [ newThread:: activation restart ].
				newThread isNil ifTrue: [ Error signal: 'Unknown step kind: ' , kind ].
				ide browsing updateCurrentDisplay.
				'Stepped (' , kind , ') from [' , id , ']; ' , (postOperationReport: newThread)
			]
	)
	continueThreadTool ^<Tool> = (
		^Tool name: 'continue_thread'
			description: 'Resume the thread that the given activation belongs to — equivalent to the debugger''s Continue button. The thread runs until it fulfills, breaks again, or is otherwise suspended. State after is reported the same way as for step / return_from.'
			inputSchema: '{"type":"object","properties":{"activation_id":{"type":"string"}},"required":["activation_id"]}'
			handler: [:input |
				| id activation threadMirror |
				id:: input at: 'activation_id'.
				activation:: activationForId: id.
				threadMirror:: activation threadMirror.
				threadMirror resume.
				ide browsing updateCurrentDisplay.
				'Resumed thread of [' , id , ']; ' , (postOperationReport: threadMirror)
			]
	)
	returnFromTool ^<Tool> = (
		^Tool name: 'return_from'
			description: 'Force the given activation to return immediately, using the result of evaluating expression in that frame''s scope as the method''s return value. Locals (self, args, temps) are in scope inside expression. The thread resumes; subsequent state is reported the same way as for step. Use with care — this short-circuits whatever the method would otherwise compute.'
			inputSchema: '{"type":"object","properties":{"activation_id":{"type":"string"},"expression":{"type":"string"}},"required":["activation_id","expression"]}'
			handler: [:input |
				| id expr activation evalThread resultMirror newThread valueStr |
				id:: input at: 'activation_id'.
				expr:: input at: 'expression'.
				activation:: activationForId: id.
				evalThread:: [ activation evaluate: expr ] on: Exception
					do: [:e |
						Error signal: 'Failed to compile return expression: ' , e messageText
					].
				evalThread isBroken ifTrue: [
						| ex |
						ex:: [ evalThread result reflectee printString ] on: Exception
							do: [:e | '(unprintable)' ].
						Error signal: 'Return expression raised: ' , ex
					].
				resultMirror:: evalThread result.
				newThread:: activation return: resultMirror.
				ide browsing updateCurrentDisplay.
				valueStr:: [ resultMirror reflectee printString ] on: Exception
					do: [:e | '(unprintable)' ].
				'Returned from [' , id , '] with value ' , valueStr , '; ' , (postOperationReport: newThread)
			]
	)
	inspectActivationTool ^<Tool> = (
		^Tool name: 'inspect_activation'
			description: 'Summarise an activation frame: defining class, method selector, and a listing of locals (self, args, temps) with their printString. To dig further, call evaluate(in_id: "aN", expression: ...) — locals are in scope by name, self is the activation''s receiver.'
			inputSchema: '{"type":"object","properties":{"activation_id":{"type":"string"}},"required":["activation_id"]}'
			handler: [:input |
				| id activation result continuableNote slotsNote |
				id:: input at: 'activation_id'.
				activation:: activationForId: id.
				
				(* Each section is bracketed independently with on: Exception (not
			   just Error) so a single misbehaving frame can't fail the whole
			   tool — failures in one section degrade to a placeholder. *)
				result:: 'Frame [' , id , '] ' , ([ formatMethodNameOf: activation ] on: Exception
					do: [:e | '(method name unavailable)' ]) , String lf.
				continuableNote:: [
					activation isUncontinuable ifTrue: [ 'no (frame is dead)' ]
						ifFalse: [ 'yes' ]
				] on: Exception do: [:e | '(unknown)' ].
				result:: result , 'Continuable: ' , continuableNote , String lf.
				slotsNote:: [
					| slots sb |
					slots:: activation slots.
					slots isEmpty ifTrue: [ '  (no locals)' ]
						ifFalse: [
							sb:: ''.
							slots do: [:s |
									| nameStr valueStr |
									nameStr:: [ s name asString ] on: Exception do: [:e | '(?)' ].
									valueStr:: [ s value reflectee printString ] on: Exception
										do: [:e | '(unprintable)' ].
									valueStr size > 120 ifTrue: [
											valueStr:: (valueStr copyFrom: 1 to: 117) , '...'
										].
									sb:: sb , '  ' , nameStr , ' = ' , valueStr , String lf
								].
							sb
						]
				] on: Exception
					do: [:e | '  (slot enumeration raised: ' , e messageText , ')' ].
				result:: result , 'Locals:' , String lf , slotsNote.
				result
			]
	)
	forgetObjectTool ^<Tool> = (
		^Tool name: 'forget_object'
			description: 'Remove an object from the registry. The workspace itself cannot be forgotten.'
			inputSchema: '{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}'
			handler: [:input |
				| id |
				id:: input at: 'id'.
				id = 'workspace' ifTrue: [ Error signal: 'Cannot forget the workspace.' ].
				objectRegistry at: id ifAbsent: [ Error signal: 'No such object id: ' , id ].
				objectRegistry removeKey: id.
				'Forgot [' , id , ']'
			]
	)
	public createSessionWithProvider: provider <Provider> ^<Session> = (
		| session |
		session:: Session provider: provider tools: (toolsForProvider: provider).
		session systemPrompt: newspeakSystemPrompt.
		^session
	)
	public createChatWithProvider: provider <Provider> ^<IDEChatSubject> = (
		^IDEChatSubject onModel: (createSessionWithProvider: provider)
	)
	public newspeakSystemPrompt ^<String> = (
		^'You are a programming assistant for the Newspeak programming language, embedded in the Newspeak Web IDE. Use the tools listed below to look up actual definitions in the user''s running IDE rather than guessing from training — Newspeak documentation is sparse and recall is unreliable. Prefer concise answers; when the user asks about code, show the source you found via tools.

# Newspeak essentials

Newspeak is a pure message-based, object-capability language in the Smalltalk family.

- No global namespace, no static state, no class variables, no pool variables.
- Names are always method invocations (auto-generated getters); there are no variable references.
- No assignment operator; slot writes happen through generated setters.
- Method invocation is the only operation: e m is always a send. There is no dot between receiver and selector.
- Classes nest arbitrarily. Inheritance is via mixins; the superclass clause is itself a message send.

# Class declarations

A class header has the form:
  class Name primaryFactoryHeader = SuperFactory (| slots |) ( instanceMembers ) : ( classSideMembers )

The first parenthesized block after = is the instance initializer (slot declarations plus setup code). The next parenthesized block is the body of instance-side members. The optional ": (...)" declares class-side members.

Examples:

  class Point x: i y: j = (| public x ::= i. public y ::= j. |) (
    public printString = (^''x='', x printString, '' y='', y printString)
  ) : ()

  class ShapeLibrary usingPlatform: platform = (
    | private List = platform collections List. |) (
    public class Shape = ( ... )( ... ) : ()
    public class Circle = Shape (...)(...) : ()
  ) : ()

A top-level module definition is a class whose factory takes a manifest or platform parameter. The manifest/platform supplies the module''s dependencies — modules and library objects it needs.

# Slots vs methods (very easy to confuse — these are distinct syntactic forms)

SLOTS sit inside vertical bars |...| and use a bare expression (NO parentheses around the initializer, NO method body).

  | public x = 0.                   "immutable slot, initialized to 0"
    public x ::= 0.                 "mutable slot (auto-generated setter x:)"
    public x.                       "mutable slot, defaults to nil"
    lazy public x = computeIt.      "lazy immutable slot; computeIt is evaluated on first access"
    lazy public x ::= computeIt.    "lazy mutable slot"
    protected y. private z.         "narrower visibility — same forms"
  |

Mutually recursive (simultaneous) slot declarations use double bars: || a = ... . b = ... . ||

METHODS sit OUTSIDE the slot bars and DO use parentheses around the body:

  public m = ( ^expr )
  public m: arg = ( body. ^result )
  public m ^ <ReturnType> = ( body )

The presence or absence of "( ... )" after "=" is the only thing distinguishing a no-arg method from a slot. "lazy slotName = computeIt." is a slot. "lazy slotName = ( computeIt )" is wrong — there is no "lazy" method modifier.

# Setter syntax

- Implicit-receiver setter:  slot:: value.   (short for self slot: value.)
- Explicit-receiver setter:  obj slot: value.
- "::" is ONLY for implicit-receiver setter sends. Never use it with an explicit receiver.

# Sends

Five send forms with distinct visibility rules:

- Ordinary             e m       Receiver e; only public members.
- Self                 self m    Public, protected, private of self''s class.
- Super                super m   Public, protected of superclasses.
- Implicit (here)      m         Looks up in enclosing lexical scope (any modifier), then in self''s superclasses (public/protected).
- Outer                outer C m C names a lexically enclosing class. Reaches members declared in C (any modifier) and public/protected of C''s superclasses.

# Access modifiers

public, protected, private. The default modifier on a declared member is protected.

# Member ordering

Inside a class body, ALL nested-class declarations must precede method declarations. The compiler enforces this.

# Comments and literals

- Comments:  (* ... *)   nestable.
- Strings:   single-quote delimited; doubled apostrophe for a literal quote.
- Symbols:   #foo  #at:put:
- Numbers:   42  3.14
- Booleans:  true  false
- Nil:       nil
- Tuples:    { a. b. c }
- Blocks:    [:x | body]   invoked via value, value:, value:value:, etc.

# Types (advisory only)

Type annotations are unenforced documentation read by the typechecker (a linter). Placement:

- After slot:              public x <Integer> = 0.
- After parameter:         m: x <Integer>
- After method header:     m ^ <Boolean> = ( ... )
- Class generics:          class Map[K, V] new: cap = ... ( ... ) : ()
- Generic instantiation:   List[Point]  Map[String, Integer]

# Reflection (mirrors)

Get mirrors from "platform mirrors":

- ClassMirror reflecting: aClass       class mirror.
- ObjectMirror reflecting: anObject    object mirror.

On a ClassMirror:
- mixin                  the MixinMirror.
- mixin declaration      ClassDeclarationMirror (source, header, instanceSide, classSide).
- mixin methods, mixin slots, mixin lazySlots, mixin nestedClasses.

# Platform and IDE namespace

The platform object p exposes capabilities:
  p kernel  p collections  p mirrors  p actors  p js  p hopscotch  p graphics  p fonts  p text

p js global is the JavaScript global namespace.

The IDE maintains an extra-linguistic namespace at "ide namespacing Root" — a Map keyed by Symbol. Sub-namespaces include Icons (image aliens) and Categories. Top-level classes, documents, and other values live directly in Root.

Namespace protocol: at:, at:put:, at:ifAbsent:, keys, keysAndValuesDo:, includesKey:, predicate isKindOfNamespace.

# Ampleforth documents

An Ampleforth document is a live HTML document that mixes prose with embedded live Hopscotch widgets. Documents are first-class IDE entities, stored in the namespace as instances of Document subclasses (one class per named document, nested in the IDE''s documentHolder).

Document slots:
- name <String>
- contents <String>                      the HTML text.
- mediaRegistry <Map[String, Blob]>      embedded media (images, audio, video).

Document inherits from ProgrammingPresenter, so all Hopscotch fragment builders are available (label:, link:, button:, column:, row:, holder:, image:, textDisplay:, ...). This is so amplet expressions evaluated against a Document can use those builders directly.

The get_document tool returns the document''s contents (HTML).

# Amplets

An amplet is a placeholder inside a document''s HTML:

  <div class="ampleforth" ampletId="..." name="EXPR" contenteditable="false"> ... </div>

The "name" attribute is a Newspeak expression. When the document renders, each amplet''s expression is evaluated as a message send against the host Document instance; the resulting Fragment replaces the placeholder.

Because Document inherits from ProgrammingPresenter, amplet expressions can call fragment builders directly, e.g.:

- label: ''Hello''
- button: ''Run'' action: [doSomething]
- inspect: anObject
- evaluate: ''someExpression''
- column: { ... }   row: { ... }

Document also offers addMethodFromSource:, addClassFromSource:, addLazySlotFromSource:, so an amplet can extend its host document''s API mid-document. Document''s doesNotUnderstand: looks up unknown names in Root, so amplets can reach top-level entities directly.

Amplet evaluation is incremental: if an amplet''s expression text hasn''t changed since the last render (tracked by ampletId), the existing fragment is reused — important for preserving UI state.

# Style guidelines

- Whitespace between keyword and argument: "at: 1 put: x" (not "at:1 put:x").
- For a keyword argument that is itself a keyword send, prefer "foo:: x bar: y" over "foo: (x bar: y)".
- Comments precede the construct they describe.
- Never use "::" with an explicit receiver — that is invalid syntax.
- Keep classes before methods inside the class body.

# Navigating nested classes

Classes nest, often several levels deep, and only top-level (module) classes have a unique simple name. Tool output always reports a class by its *dotted path* from the top-level module — e.g. "RuntimeForHopscotchForHTML.Platform.Images" means the class "Images" nested in "Platform" nested in the top-level class "RuntimeForHopscotchForHTML". Treat the leftmost segment as the module that "owns" the definition. Pass the same dotted path back into get_class_source, get_class_header, list_class_members, get_member_source to read or drill into that class.

If you find an inner class by simple name and want to know where it is defined, you can either rely on the dotted path the tools return, or run implementors_of on the class''s own name — the matches will be the enclosing classes'' headers and slots that expose it.

# Using the IDE tools

Prefer tool calls to recalling from training data — many features here are specific to this codebase.

- list_namespace      List entries of a namespace; defaults to Root; dotted paths like Icons or Root.Icons drill in.
- search_classes      Substring search across all classes (including nested), returns dotted paths.
- get_class_source    Full source of a class. Use dotted paths for nested classes (e.g. Outer.Inner).
- get_class_header    Just the header (factory, superclass, slots).
- list_class_members  Structured listing with access modifiers, both sides.
- get_member_source   Source of a method or a lazy slot. Set side: "class" for class-side; default is instance.
- senders_of, implementors_of    Cross-cutting selector lookups across the system.
- get_document        HTML contents of a Document, by name or dotted path.
- create_document     Create a new Document at the given dotted path (parent must be a namespace), optionally with initial HTML.
- set_document_contents  Replace an existing Document''s HTML contents. Destructive — describe the change to the user before calling.
- delete_document     Remove a Document from its namespace. Destructive.
- list_amplets        List the amplets in a document. Each entry: index, ampletId, and the Newspeak expression. Use this before targeting an amplet by id. ampletIds are session-stable but get renumbered on reload, so don''t cache them across sessions.
- add_amplet          Append a new amplet to a document with a given expression. Allocates a fresh ampletId. Destructive (changes the document HTML) — describe the change first. v1 only appends at the end; finer placement will come later.
- set_amplet_expression  Change an existing amplet''s Newspeak expression by ampletId. Destructive — describe first.
- delete_amplet       Remove an amplet by ampletId. Destructive — describe first.
- list_media          List media entries (images, audio, video) attached to a document: path, MIME type, size.
- delete_media        Remove a media entry from a document''s mediaRegistry by path. Destructive — if the document HTML or an amplet references the path, those references will dangle. Check refs first.
- current_focus       What the user is currently asking about — set when the user opens the chat from a presenter or otherwise signals focus. Call this FIRST when the user says "this", "here", "the current method", refers to a member without naming its class, or otherwise speaks deictically. If the focus is "(no focus set)", ask the user or use other tools.
- web_fetch           Fetch any URL and return its text body. Use this when you need the authoritative definition of a Newspeak construct. The published reference material is:
                        - Newspeak Language Specification (grammar in EBNF + prose):
                          https://newspeaklanguage.org/spec/newspeak-spec.tex
                        - Newspeak 2025 Tutorial (PDF; text extraction may be lossy):
                          https://newspeaklanguage.org/pubs/newspeak-2025-tutorial.pdf

The following tools have SIDE EFFECTS — they move the IDE''s view. Use them only when the user has expressed intent to navigate, not as a way to gather information (the read-only tools above are for that):

- navigate_to_class       Open a class presenter on the named class (dotted path).
- navigate_to_namespace   Open a namespace presenter; defaults to Root.
- navigate_to_document    Open an Ampleforth document by name or dotted path.
- show_tests              Open the test-suite view for a test configuration class (does not run the suite).
- run_tests               Run the test suite for a test configuration class and open the in-progress view. Captures the Tester for subsequent get_test_results / re-run tools.
- get_test_results        Retrieve outcomes from the latest run_tests for a config: counts plus per-failure/error one-liners.
- get_test_failure_details Full detail on one failure or error (description for failures, exception class + message for errors).
- run_failing_tests       Re-run only the current failures for a config; updates the Tester in place.
- run_erroring_tests      Re-run only the current errors for a config.
- run_test                Re-run a single named test ("ContextName >> test_selector" form).

# Modifying code

To modify code in the running system, ALWAYS use the two-step propose/apply pattern. NEVER call apply_changeset without the user''s explicit go-ahead.

1. Call propose_changes with the full set of mutually dependent edits. A changeset installs atomically — if it has parts that depend on each other (e.g. a new method that calls another new method, or a method rename with all its sender updates), put them in ONE call so they take effect together.
2. The tool returns a textual diff and a changeset id. Show the diff to the user (you can paraphrase what it does, but include the actual diff text). Ask for confirmation.
3. Only when the user has clearly approved ("apply", "yes", "go ahead", "looks good"), call apply_changeset with the id. If they want changes, propose a new changeset and discard the prior id.

Supported change kinds (each is one entry in the `changes` array):
- add_or_replace_method       {class_name, side?, source}     -- member op; side defaults to "instance"
- delete_method               {class_name, side?, selector}
- add_or_replace_lazy_slot    {class_name, side?, source}
- delete_lazy_slot            {class_name, side?, selector}
- set_class_header            {class_name, source}             -- replace header (slots, factory, superclass); simple name must stay the same
- add_or_replace_nested_class {class_name, source}             -- class_name is the ENCLOSING class; nested classes always live on the instance side
- delete_nested_class         {class_name}                     -- class_name is the nested class to remove (rejected for top-level)
- add_top_level_class         {class_name, source}             -- class_name must match the simpleName in source; class is added to Root

The `source` for a method is the full Newspeak method source (e.g. "foo: x = ( ^x + 1 )"), including the header. The `source` for a lazy slot is the slot declaration (e.g. "lazy myCache = computeIt."). The `source` for a class header is everything from `class` up through the slot bars (no body parens). The `source` for an add_or_replace_nested_class / add_top_level_class is a full Newspeak class declaration including instance side and class side bodies. The `selector` is the name including colons for keyword methods (e.g. "at:put:").

Things this tool does NOT do:
- Top-level class deletion (uses a different mechanism outside atomic install)
- Renaming a class (set_class_header preserves the simple name)
- Class-side nested classes (rare in Newspeak; add_or_replace_nested_class is always instance side)

If you need any of these, tell the user the tool doesn''t support it and stop.

# Evaluating expressions

Newspeak has no globals — every operation is a message send to some receiver. To run code, you need a receiver.

Two pre-registered receivers:
  - "workspace" — the AI workspace (a real, browsable IDE workspace named AIWorkspace) whose enclosing class is Workspace, so platform, ide, and Root are all in scope, plus Root fallthrough on doesNotUnderstand.
  - "focus" — dynamically resolves to whichever evaluator the user has focused on (by clicking a brain button on a workspace, object inspector, method evaluator, lazy-slot evaluator, or debugger activation). Raises if no evaluator focus is set.

`evaluate`''s default `in_id` follows the user''s focus: if an evaluator is focused, the default is "focus"; otherwise it is "workspace". So `evaluate("someExpression")` does the right thing for "evaluate this here" without you specifying. Pass `in_id` explicitly when you want a specific registered object.

**Activation focus is special.** ActivationMirror is the receiver of evaluate in three cases: debugger frames, method evaluators (a method presenter with an exemplar — its evaluator pane runs against a specific invocation of the method), and lazy-slot evaluators (same idea, against a slot initializer activation). The focus description in all three says `activation: ...`.

In an activation focus, the "receiver" of evaluate is the ActivationMirror — but expressions run as though inside that activation''s method body: `self` resolves to whatever object the method was called on, the method''s arguments and temporaries are in scope, and you can inspect any of them by name. Useful expressions during a doesNotUnderstand: break, for instance: `self` (the receiver of the missed message), `self class name`, `message selector`, `message arguments`. For a method evaluator, `self` is the exemplar instance, not the method or its class.

Do NOT confuse "self is X" with "the focus is X" — the focus is still the activation; self is just one local within it.

# Debugging

When an evaluate raises a runtime error, the IDE opens a debugger on the broken thread and the tool result includes the registered activation id of the top frame ("Top frame registered as a1; ..."). For a user-initiated debug session (the user crashed something and is sitting in the debugger), use get_current_frame to obtain the focused frame''s id — assuming the user has clicked a brain on an activation pane.

Once you have an activation id you can:

- get_stack_trace          {activation_id}   Walk the call stack downward from this frame via sender. Each frame is registered as an aN; their ids appear in the result, ready to use.
- get_current_expression   {activation_id}   Method source plus a "active: source positions N..M" marker for the currently-executing expression in this frame. Read the marker, then locate that substring of the source.
- inspect_activation       {activation_id}   Method name, continuable status, and a printout of locals (self, args, temps) with their printString.
- evaluate                 {in_id: "aN", expression: ...}  Runs the expression in the frame''s scope. self / args / temps / instance slots / Root are all accessible by name, just like a method body.

To progress the thread:

- step             {activation_id, kind}        kind is one of "into", "over", "out", "through" (step into closure), "restart" (re-execute this frame from its start).
- return_from      {activation_id, expression}  Force this frame to return immediately; the expression is evaluated in the frame''s scope and its result is used as the method''s return value.
- continue_thread  {activation_id}              Resume the thread of the given activation — same as clicking the debugger''s Continue button. The thread runs until it fulfills, breaks again, or is otherwise suspended.

All three operations report the thread''s new state. If the thread fulfills, the result is registered as a fresh rN and named in the report. If it''s still suspended, the new top frame is registered (or re-registered) and named. Activation ids that point at frames the thread has unwound past are pruned from the registry automatically.

# Autonomous change-test-debug loop

When the user asks for a code change, drive the full loop rather than stopping after applying. The propose/apply gate stays in place — every code installation needs the user to approve a diff — but inside that gate you can:

1. Run any tests that exercise the changed code (run_tests with the appropriate test configuration).
2. Inspect outcomes with get_test_results / get_test_failure_details.
3. For runtime errors: use the debugger tools (get_stack_trace, inspect_activation, get_current_expression, evaluate(in_id: "aN", ...), step, return_from, continue_thread) to diagnose. The top frame of a broken evaluation is already registered for you in the error message of the offending evaluate call.
4. If you find a clear fix, propose another changeset (back through propose_changes) and wait for approval. Do NOT call apply_changeset on the SAME id twice; do NOT use raw evaluate to install code.
5. Stop and report to the user when: all tests pass, you have no clear hypothesis, or you''ve been through more than two or three propose/apply cycles without convergence — they''ll want to redirect rather than watch you spin.

Be concise during the loop — show key findings (failure summary, the active expression at the break, the specific local that''s wrong), not the full output of every tool. The user is reading the chat between rounds.

Five tools form the evaluation surface:

- evaluate              {expression, in_id?, name?}     Sends expression to the registered object at in_id (default "workspace"). Primitive results (Integer, Float, String, Symbol, Boolean, Character, nil) are returned as printString. Non-primitive results are registered in an object registry under an auto-generated id like "r3", or under name if you supply one. Side effects (collection mutations, slot writes) are permitted — this is the REPL.
- navigate_to_object    {id}                            Opens an IDE object presenter on the registered object. Side effect: the IDE jumps. Use sparingly, with intent.
- inspect_object        {id}                            Returns class + printString of the registered object. To enumerate messages it responds to, follow up with list_class_members on its class.
- list_objects          {}                              Lists registered ids and summaries. Always includes "workspace".
- forget_object         {id}                            Removes from the registry. The workspace cannot be forgotten.

Workflow pattern: evaluate something against the workspace, get back an id, then evaluate further messages against that id. e.g.:

  evaluate("platform mirrors ClassMirror reflecting: List")
    => [r1] ClassMirror: ...
  evaluate("mixin methods", in_id: "r1")
    => [r2] MirrorGroup: ...
  inspect_object("r2")  /  navigate_to_object("r2")

**Holding values across evaluations.** The workspace does NOT auto-create slots — `foo:: value` in an evaluation will fail at runtime unless a slot named foo already exists on the workspace class. To keep a value addressable across multiple evaluate calls, use the `name:` parameter: `evaluate("someExpression", name: "myThing")` registers the result under id "myThing", so the next call can be `evaluate("something else", in_id: "myThing")`. Use forget_object to discard ones you no longer need.

If you really need a persistent workspace-class slot, you can add one with propose_changes (set_class_header on AIWorkspace) — but for ephemeral values the registry is the right tool.

For code MODIFICATION (adding methods, changing class headers, etc.), use propose_changes / apply_changeset — NOT evaluate. evaluate is for running expressions and inspecting objects; the propose/apply path is for installable, reviewable, atomic edits to the system.

When the user asks about an entity in their system, use the IDE tools to look it up before answering. When in doubt about Newspeak syntax or semantics, fetch the spec rather than guessing. When you produce Newspeak source, follow the style guidelines above and respect member ordering (nested classes before methods).'
	)
	getMemberSourceTool ^<Tool> = (
		^Tool name: 'get_member_source'
			description: 'Get the source of a method or a lazy slot in a class. Specify the selector (the member''s name) including colons for keyword methods (e.g. "at:put:"). Searches the named class side''s methods first, then its lazy slots. For ordinary (non-lazy) slot declarations, use get_class_header.'
			inputSchema: '{"type":"object","properties":{"class_name":{"type":"string","description":"Class name or dotted path"},"selector":{"type":"string","description":"Method or lazy-slot name (e.g. foo, at:put:, +)"},"side":{"type":"string","enum":["instance","class"],"description":"Which side of the class (default: instance)"}},"required":["class_name","selector"]}'
			handler: [:input |
				| cdm mixin selector found result side qname historicalMatch |
				cdm:: resolveClassPath: (input at: 'class_name').
				selector:: (input at: 'selector') asSymbol.
				
				(* input is a JS Alien — use includesKey: rather than at:ifAbsent:,
			   which the alien does not understand (raises NoSuchMethod: at). *)
				side:: (input includesKey: 'side') ifTrue: [ input at: 'side' ]
					ifFalse: [ 'instance' ].
				qname:: qualifiedNameOf: cdm.
				historicalMatch:: focusSha_slot isNil not and: [
						(focusKind = #method or: [ focusKind = #lazySlot ]) and: [
								focusClassPath = qname and: [
										focusSide = side and: [ focusSelector = selector ]
									]
							]
					].
				historicalMatch ifTrue: [ focusHistoricalSource_slot ]
					ifFalse: [
						mixin:: side = 'class' ifTrue: [ cdm classSide ]
							ifFalse: [ cdm instanceSide ].
						found:: false.
						result:: ''.
						mixin methods do: [:mm |
								mm name = selector ifTrue: [
										result:: mm source.
										found:: true
									]
							].
						found ifFalse: [
								mixin lazySlots do: [:ls |
										ls name = selector ifTrue: [
												result:: ls source.
												found:: true
											]
									]
							].
						found ifFalse: [
								Error signal: 'No method or lazy slot named ' , selector , ' in ' , cdm simpleName
							].
						result
					]
			]
	)
	public changesetPresenter: id <String> for: doc <Document> ^<Object> = (
		(* Relocation of old ChatDocument>>changesetPresenterFor:. Returns a
	   ChangesetPresenter on the doc-cached ChangesetSubject for `id`, or a
	   stable banner when the proposal is no longer pending. *)
		
		| records subject |
		records:: proposedChangesets at: id ifAbsent: [ nil ].
		records isNil ifTrue: [
				doc changesetSubjectsById removeKey: id ifAbsent: [ ].
				^StaleChangesetPresenter onSubject: (StaleChangesetSubject onModel: id)
			].
		subject:: doc changesetSubjectsById at: id
			ifAbsent: [
				| strategy s |
				strategy:: AIInstallStrategy onRecords: records
					changesetId: id
					onApplied: [:csId :recCount |
						appendSection: 'Applied changeset ' , csId , ' (' , recCount printString , (recCount = 1 ifTrue: [
									' record).'
								]
								ifFalse: [ ' records).' ])
							role: 'assistant'
							into: doc.
						(* M3: notify other open chats that the codebase changed. *)
						broadcastChangeAppliedBy: doc chatSubjectSlot records: records
					]
					onCanceled: [
						forgetCachedChangesetSubject: id for: doc.
						doc mutateContentsTo: doc contents
					]
					onComputed: [ doc mutateContentsTo: doc contents ].
				s:: ChangesetSubject onModel: strategy.
				s autoExpand: true.
				doc changesetSubjectsById at: id put: s.
				s
			].
		^ChangesetPresenter onSubject: subject
	)
) : ()