refactor: overhaul plugin architecture

[NoOne7135]

No description provided.

[Copilot]

Pull request overview

This PR refactors the agent plugin into a layered architecture (domain/application/llm/transport/persistence/tools), introduces a provider port for the LLM runtime, and adds persistent checkpoint support for HITL (human-in-the-loop) resumes.

Changes:

• Replaces the former AgentTurnService orchestration stack with RunTurnUseCase + an LlmPort (LangGraphLlm) and typed streaming (AgentStreamChunk).
• Moves cross-cutting utilities into shared/ and domain logic into domain/, updating imports across transports/tools/tests.
• Adds AdminForth-backed checkpoint persistence (AdminForthCheckpointSaver) and reorganizes HTTP endpoints (including new chat-surface webhook endpoints).

Reviewed changes

Copilot reviewed 45 out of 53 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
types.ts	Updates plugin option types and deprecates unused fields for backwards compatibility.
transport/surfaces/speechTurnService.ts	Repoints surface implementation to new shared/domain modules.
transport/surfaces/chatSurfaceService.ts	Updates surface flow to use new domain/shared modules and masks user-facing error messages.
transport/sse/sseWriter.ts	Updates imports and documents SSE wire contract mapping.
transport/http/sessionEndpoints.ts	Uses persistence session store constant and sets HTTP status codes on auth/not-found cases.
transport/http/coreEndpoints.ts	Switches SSE emitter import and simplifies handler signatures.
transport/http/context.ts	Repoints endpoint context types to the new domain types and plugin options.
transport/http/chatSurfaceEndpoints.ts	Adds webhook endpoints for external chat surfaces.
tools/skills/registry.ts	Adds skill discovery/loading from SKILL.md directories (project + plugins).
tools/navigateUser.ts	Updates agent event imports and uses adminPublicOrigin to build external links for chat surfaces.
tools/index.ts	Updates tool dependency imports after refactor.
tools/getUserLocation.ts	Adds a dedicated tool for retrieving the user’s current AdminForth page context.
tools/fetchToolSchema.ts	Updates tool dependency imports after refactor.
tools/fetchSkill.ts	Updates skill registry import path after refactor.
tools/apiTool.ts	Updates tool dependency imports after refactor.
tools/apiBasedTools.ts	Removes verbose OpenAPI/tool invocation logging and updates structure after refactor.
tools/agentToolProvider.ts	Repoints to new tools module layout.
tests/units.test.ts	Updates unit test imports; removes AgentModeResolver characterization tests.
tests/turn_flow.test.ts	Rewrites characterization tests to drive RunTurnUseCase + typed stream chunks and resume logic.
tests/system_prompt.test.ts	Updates imports to new domain system prompt module.
tests/stream_adapter.test.ts	Adds coverage for raw LangGraph stream parsing into typed chunks.
tests/sse_emitter.test.ts	Updates imports to new SSE writer location.
tests/session_store.test.ts	Updates imports to new persistence session store location.
shared/sanitizeSpeechText.ts	Moves speech-text sanitization to shared module.
shared/errors.ts	Centralizes abort detection + error message formatting.
persistence/sessionStore.ts	Adds touchSession, saveTurnResponse, and getResumeState APIs and repoints domain imports.
persistence/checkpointStore.ts	Adds AdminForth-backed LangGraph checkpointer implementation.
llm/streamAdapter.ts	Introduces raw stream adapter/parser and interrupt normalization.
llm/modelFactory.ts	Repoints model factory to new llm agentModels module.
llm/middleware/sequenceDebug.ts	Updates tool-call event import path after refactor.
llm/middleware/apiToolsMiddleware.ts	Repoints to new tool/event modules and removes verbose logging.
llm/langGraphLlm.ts	Implements LlmPort using LangChain/LangGraph and typed stream adaptation.
llm/agentRuntime.ts	Rehomes agent runtime and adds pending-interrupts checkpoint read helper.
llm/agentModels.ts	Centralizes model creation + adapter contract and metrics logger.
llm/agentContext.ts	Updates runtime context typing and imports after refactor.
index.ts	Rewires plugin setup to new layered components, checkpointer, and endpoints.
domain/vegaLiteStreamBuffer.ts	Updates imports to new domain agent events module.
domain/turnTypes.ts	Introduces typed stream chunks, provider-agnostic messages, and narrows debug sink contract.
domain/toolCallEvents.ts	Moves tool-call debug tracking/events into domain layer.
domain/systemPrompt.ts	Repoints skill registry import to new tools location.
domain/languageDetect.ts	Moves language detection into domain, using completion adapter structured output.
domain/agentEvents.ts	Repoints tool-call event import to new domain module.
application/runTurnUseCase.ts	New single orchestration entrypoint for turn handling, streaming, persistence, and HITL resume.
application/ports.ts	Defines the provider port (LlmPort) and adapter contract (AgentModeCompletionAdapter).
agentTurnService.ts	Removed: replaced by application/runTurnUseCase.ts orchestration.
agent/turn/TurnStreamConsumer.ts	Removed: replaced by llm/streamAdapter.ts + use-case consumption.
agent/turn/TurnPromptBuilder.ts	Removed: replaced by RunTurnUseCase.buildMessages() + domain system prompt builder.
agent/turn/TurnPersistenceService.ts	Removed: logic moved into persistence/sessionStore.ts.
agent/turn/TurnLifecycleService.ts	Removed: logic moved into RunTurnUseCase.prepareTurn() + session store helpers.
agent/turn/TurnContextBuilder.ts	Removed: replaced by RunTurnUseCase.buildContext().
agent/simpleAgent.ts	Removed: replaced by llm/agentModels.ts and application-layer adapter contract.
agent/models/AgentModeResolver.ts	Removed: mode resolution now in RunTurnUseCase.resolveMode().
agent/middleware/openAiResponsesContinuation.ts	Removed as part of the architecture overhaul.

Comments suppressed due to low confidence (1)

persistence/sessionStore.ts:110

• touchSession() updates the field configured as sessionResource.createdAtField. This makes the stored/returned “created at” timestamp inaccurate and also changes /agent/get-sessions ordering semantics (it effectively becomes “last activity”). Consider adding a dedicated updatedAtField/lastActivityField to ISessionResource and using that for touch + sorting, leaving createdAtField immutable.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.