Previously, Tool.apply_ex derived a session ID from the MCP session object (or
"global" with no context) and injected it into any apply() method that declared
a session_id parameter. This is being changed because:
* the new MCP SDK v2 no longer provides session identifiers
* handling it internally is more robust anyway, since clients did not
consistently use sessions
Session handling
- Remove implicit session ID injection from Tool.apply_ex, along with the
supporting _is_session_aware property and SESSION_ID_PARAM_NAME skip logic
- SerenaAgent.create_system_prompt() now creates the session itself and reports
its id, instead of receiving session_id as an argument
Tool signatures
- InitialInstructionsTool.apply() and ActivateProjectTool.apply() now declare
session_id explicitly and rely on the LLM to pass it, rather than having it
injected
- Rename SerenaReplTool.apply()'s session parameter to session_id for consistency
with the other tools
Resolves#2061
* Many case differentiations in the agent code were replaced by
method calls in the newly introduced LanguageBackend abstraction
* The registry allows new backends to be added dynamically
(via Python packages that implement a specific entrypoint)
- Require a valid Bearer token on heartbeat and project-query requests.
- Send the configured auth_secret from clients and the query-project tool.
- Test accepted and rejected credentials, including real HTTP client requests.
- Set configuration permissions to 0600 before reading and log adjustments.
- Log chmod failures and continue loading; leave Windows permissions unchanged.
- Generate a random UUID when auth_secret is missing, null, or empty.
- Persist generated secrets and preserve configured values across reloads.
- Document the shared secret and test generation, persistence, and direct construction.
- Rename the read-only context to read_project_context and add writable project_context.
- Dispatch LSP-backed edits remotely and enforce read-only access in the calling context.
- Allow project-server facade calls independently of the target project's API restrictions.
- Update dispatch coverage for both backends and access modes; remove obsolete rejection assertions.
A language server's cache directory was determined by the language_id rather than
the language server identifier's key. The two identifiers coincided in most cases.
Facade availability:
* facades can be optional (`Facade.from_api(..., is_optional=True)`), mirroring optional tools
* `Facade.is_enabled()` is derived: a facade is available iff it has at least one enabled method
* `ApiScope.is_facade_enabled` is thereby obsolete and removed
Opt-in rule (uniform for optional facades, excluded facades and optional methods):
* methods of a facade which is not included and optional methods require explicit inclusion
* all other methods are enabled unless explicitly excluded
Application:
* the `ext` facade is optional; the query-projects mode includes it (`included_apis: [ext]`)
Configuration endpoint:
* ResponseConfigOverview: agent_interface, language_backend and facades (None in tool mode)
* facades report each facade and its methods with their enabled state (SerenaReplEntrypoint.get_facade_availability_info)
Dashboard UI:
* new rows "Interface" and "Backend"; "Languages" is shown for the LSP backend only
* new collapsible section "Active Functions" listing the facades and their methods, dimming disabled ones
* _activate_project: a project's backend override switches the backend in REPL mode (background
modes, facades, prompt parameters and backend initialisation are recomputed upon activation)
* the tool interface keeps rejecting the mismatch (fixed toolset); the error now mentions the REPL
as a workaround
* single-project sessions: in the REPL tool's description (fixed at registration)
* otherwise: in the project activation message (facades depend on the activated project)
* REPL tool description wording adjusted (listing location, notebook semantics)
Peripheral changes:
* is_tool_function_available: in REPL mode, active tools without facade counterparts count as available
* subject line must cover the entire change (abstract if necessary)
* details as concise bullet items, grouped by topic where the change spans several topics
Availability check:
* SerenaAgent.is_tool_function_available(tool_class): whether a tool's functionality is available
to the LLM (tool mode: tool active; REPL mode: an enabled facade method corresponds to the tool)
* replaces the name-based tool_is_active/tool_is_exposed (activation message, dashboard, onboarding)
Prompts:
* activation message names functions via PromptParams.get_function_name (interface-specific names)
Introduce the ext facade with list_projects and project_context: within
`with s.ext.project_context(name):`, the facades operate read-only on the given external project.
The agent's active project is switched temporarily, and methods marked with
`@facade_method(uses_project_server=True)` (all lsp methods) are executed in the project server when
the LSP backend is active (with JetBrains, the IDE serves all projects, so they run locally). The
project server gains a /call_facade_method route executing a facade method on its own REPL facades
and returning the pickled result; arguments are transferred as JSON. Editing methods are refused,
and contexts cannot be nested. This replaces the query_project tools in the REPL.
Result objects are now self-contained (picklable): renderers no longer hold the agent (only the
default length limit; the constructor interface is unchanged), LSP results carry eagerly retrieved
symbol info and reference contexts instead of renderers accessing the language server or project.
Code is now executed at module level in the session's namespace (statements executed, a trailing
expression evaluated as the result), replacing the function wrapper with global declarations that
persistence had required. This yields notebook semantics throughout: top-level bindings persist by
construction, functions resolve names from the session namespace, and `return` is no longer used
(a top-level `return` yields a syntax error with a hint). Tool description and tests updated.
Code executions of a session now share a namespace (SerenaSession.repl_namespace), which serves as
the globals of the executions: variables, functions, classes and imports bound at the top level of
the submitted code persist across calls, like the cells of a notebook. The code is wrapped in a
function at the AST level (preserving line numbers for error reporting), with the top-level names
declared global. The entrypoint `s` is re-bound before every execution, such that persisted
functions always use the current entrypoint (e.g. after a project switch). `s.vars()` lists the
persisted items, `s.clear()` removes them; the tool description explains the persistence.
The namespace is tied to the session's lifetime; the session registry additionally evicts sessions
which have been idle for too long, releasing their namespaces.
Only the three declarations carrying member curation remain (LanguageServerSymbol, ReplacementOccurrence, MatchedConsecutiveLines); the discovered type sets are unchanged.
Facades now discover all user-defined classes reachable through the annotations of their methods and
of the members of reachable types (transitively) and make them documentable via s.info, without the
types having to be declared. Explicit ReferencedType declarations serve curation only (member
whitelists, flags). TypedDicts are documented with their keys (e.g. the JetBrains symbol DTOs and
the LSP diagnostic structures), enums with their members. SymbolKind no longer needs declaring.
Referenced types are now also discovered through the parameter annotations of type members and
facade methods (not only through return types), such that e.g. SymbolKind (a parameter type of
LanguageServerSymbol.iter_ancestors) is documented along with LanguageServerSymbol. Enums are
documented with their members and values. The lsp facade declares SymbolKind as a referenced type.
Type documentation now transitively includes the declared types a type's members reference, such
that e.g. LspSymbolCollection's documentation includes LanguageServerSymbol. To avoid repeating widely
shared types, the REPL tracks per session which types have been documented: a contained type
documented earlier in the session is only pointed to (an explicit request always yields it in full).
Since MCP provides no reliable session identification and clients keep a stdio server across
conversations, the REPL's session identity is supplied by the LLM: the instructions (system prompt)
establish a SerenaSession and state its id, and the REPL tool takes a required session_id parameter.
Sessions are managed by a SessionRegistry (creation on demand, LRU eviction). Tools which may be
called before the instructions have been read (activate_project, initial_instructions) are unchanged.
The REPL overview (tier 0, part of the tool description) now names the result type of methods
returning objects that can be processed in code (e.g. `find_symbol -> LspSymbolCollection`), such
that type documentation can be requested alongside a facade in one turn.
The facade description (tier 1) documents the common operations in full, summarises methods marked
as niche (new flag of facade_method; not yet set anywhere) with a pointer to their documentation,
and lists result types by name only. Type documentation (tier 2) is provided on request only;
provide_info_with_facade remains available but is no longer set for any type.
The REPL tool description states this protocol, in particular that facade descriptions do not
include result types and that type documentation should only be requested for processing results in
code.
Facades declare the types their methods return or contain as ReferencedTypes (with an optional
whitelist of members for curation, e.g. for LanguageServerSymbol, and a flag for inclusion in the
facade description). Type documentation is generated from class docstrings, attribute annotations,
properties and method signatures/docstrings, and is available via s.info("<facade>.<Type>") or by
bare type name; method documentation points to the documentation of a referenced return type.
Annotations are rendered without module paths, such that the names in signatures are the names by
which types can be looked up. s.info accepts several items at once, reporting unknown items inline.
All APIs declare their result types; result classes declare their attributes at class level.
Introduce ConfigApi, exposing Serena's configuration and session state: get_current_config and
open_dashboard (both non-editing). The corresponding tools delegate to the API via ConfigApiMixin.
As on the tool side, opening the dashboard is only offered if the dashboard is enabled and not
opened automatically; the condition is shared (_is_dashboard_openable) and applied to the API scope
via a NamedApiInclusionDefinition, the API-side counterpart of NamedToolInclusionDefinition.
Prompt parameters (available tools/markers and the tool name mapping) are now computed per agent
interface (SerenaAgent.PromptParams). In REPL mode, the available tools comprise the exposed tools
and the enabled facade methods, and the tool name mapping resolves tool names to the qualified names
of the corresponding facade methods (e.g. `lsp.find_symbol`), such that prompts refer to operations
as they are used in REPL code. The parameters are re-computed whenever the active tools change.
FacadeMethod refers to its parent facade and provides facade_name and qualified_name; its name is
taken from its info. Prompt templates use the tool name mapping consistently (fixing a template
syntax error in the editing mode) and use interface-neutral wording.
Introduce AgentInterface (tools/REPL) as a setting in the global configuration, overridable per
project (resolution: project > global > default "tools") and via the CLI option --agent-interface.
The interface is fixed for the session, like the language backend.
In REPL mode, the set of exposed tools is fixed: the REPL tool, initial_instructions and (unless in a
single-project session) activate_project. Tool inclusion/exclusion definitions do not apply in REPL
mode, as they pertain to the tool interface; the REPL is configured via API inclusions/exclusions.
The REPL tool is optional in tool mode.
SerenaAgent.is_single_project records whether the session is a single-project session.
FacadeMethodInfo gains corresponding_tool (the tool class offering the same functionality) and
get_corresponding_tool_name, and every API method with a tool counterpart names it in its
facade_method decorator. This enables applying tool-level exclusions to API methods and rendering
prompt conditions based on tools.
Since the API modules now refer to the tool classes, the tools import the APIs locally (in the
mixins' _api methods), and the symbol tools' symbol_dict_grouper attributes become properties.
Introduce ShellApi with the single editing operation execute_shell_command, which returns a
ShellCommandOutput exposing stdout, stderr, return code and working directory to code and rendering
as JSON as before. Keeping shell command execution in its own facade makes it a natural unit for
exclusion. The shell command tool delegates to the API via ShellApiMixin; the shell facade is always
part of the REPL.
Introduce FsApi, exposing operations on the project's files as units: read_file, create_text_file,
list_dir, find_file and search_for_pattern. The boundary to the edit facade, which modifies content
within existing files, is stated in the facade description. Results expose their data to code
(FileContent, DirectoryListing, PatternMatches) and render as before; the pattern search's
shortening ladder moves from the tool into PatternMatchesRenderer.
The file tools delegate to the API via FsApiMixin. The fs facade is always part of the REPL.
Introduce MemoryApi, exposing the memory operations list_memories, read_memory, write_memory,
edit_memory, rename_memory and delete_memory (the latter four marked as editing operations) as well
as onboarding, which provides the onboarding instructions. list_memories returns a MemoryList, which
exposes the (writable and read-only) memory names to code and renders as JSON.
The memory tools and the onboarding tool delegate to the API via MemoryApiMixin; the onboarding tool
retains its check for the availability of the memory writing tool. The mem facade is always part of
the REPL.
The modes no-onboarding, no-memories and benchmark exclude the corresponding APIs (mem.onboarding,
or the mem facade as a whole), mirroring their tool exclusions.
Broken first-party imports previously went undetected, since the rule was globally disabled to
accommodate optional extras and platform-specific modules. These are now handled narrowly:
per-file overrides for the agno integration (optional extra, not installed in CI) and for the
pywebview integration (several macOS-only imports), and an inline suppression for the single
macOS-only import in the dashboard.
Introduce EditApi as the facade for editing operations which depend
only on the code editor abstraction and thus work with any language
backend: create_text_file, replace_content, replace_in_files, the
optional line-level operations delete_lines, replace_lines and
insert_at_line, and the symbol-level operations replace_symbol_body,
insert_after_symbol and insert_before_symbol (moved from LspApi, which
retains the LSP-specific rename_symbol and safe_delete_symbol).
replace_in_files builds on MultiFileReplacement: a dry run returns a
ReplacementPreview, which exposes the occurrences to code and renders
the listing of prospective changes; rejections raise a ValueError
carrying the listing where applicable.
FacadeApi gains a backend-agnostic _create_code_editor; the LSP API's
retriever-based factory is renamed to _create_ls_code_editor. The
editing tools (file and symbol level) delegate to EditApi via
EditApiMixin, retaining only the diagnostics context. The edit facade
is always part of the REPL.
Introduce MultiFileReplacement (in serena.util.text_utils, alongside
MultiFileContentReplacer), which owns the logic previously spread over
the tool's private methods: resolving the files in scope (via the
project's file collection and glob filtering, which the tool had
re-implemented), finding occurrences, resolving occurrence ids with
diagnostics, the safety checks for blind application (no matches,
expected count, ambiguous matches), rendering the listing of
prospective changes and applying the selected occurrences. Rejections
are signalled via ReplacementRejectedError, which indicates whether
the listing should accompany the message, leaving presentation
(listing, length limit, diagnostics context) to the tool.
EditedFileContext moves from tools_base to code_editor, where it
belongs (re-exported from serena.tools); Project.create_file_collection
is now public; Tool gains _resolve_max_answer_chars.
Facade methods are now declared explicitly via the facade_method
decorator, which attaches FacadeMethodInfo (optional, beta, can_edit)
mirroring the tool markers; undecorated methods are never exposed.
All LspApi and JetBrainsApi methods are decorated accordingly
(JetBrains methods are non-optional, as the facade only exists with
the JetBrains backend).
Which facades/methods are enabled is determined by an ApiScope, which
is built by applying ApiInclusionDefinitions (included_apis,
excluded_apis, referencing facades or facade methods such as "lsp" or
"lsp.find_symbol") from the global configuration, the context, the
active modes and the project configuration, in that order. Optional
methods and all methods of an excluded facade must be included
explicitly; other methods are enabled unless excluded. For read-only
projects, editing methods are excluded. The entrypoint omits facades
which are not enabled.
The REPL is re-created whenever the active tools are updated (mode
switch, project activation), as it depends on the same configuration.
The new settings are read from project.yml and documented in all
configuration templates.
LspApi now covers all language server-backed operations:
restart_language_server, get_symbols_overview, find_symbol,
find_referencing_symbols, find_implementations, find_declaration,
get_diagnostics_for_file, get_diagnostics_for_symbol,
replace_symbol_body, insert_after_symbol, insert_before_symbol,
rename_symbol and safe_delete_symbol.
Result objects carry their rendering policy:
* LspSymbolCollectionRenderer was generalised (symbol_dicts_,
child_inclusion_predicate) and is reused by find_implementations
* LspSymbolsOverviewRenderer renders a file's overview with the
depth-0/kind-count shortening ladder
* LspSymbol/LspSymbolRenderer represent a single symbol
(find_declaration), preserving the dict output shape
* LspReferenceCollection with its renderer (context lines, per-file
counts, total count)
* LspDiagnostics wrapping GroupedDiagnostics
The symbol tools are now thin adapters which delegate to the API via
the LspApiMixin (the JetBrains tools use JetBrainsApiMixin
analogously, replacing the intermediate tool base class). Editing
tools retain the DiagnosticsContext wrapper, which the API does not
use; DiagnosticsContext moved to serena.lsp.lsp_diagnostics and is
created via EditingToolWithDiagnostics.diagnostics_context.
SUCCESS_RESULT moved to serena.facades.facade (the API cannot import
from serena.tools without an import cycle); serena.tools re-exports it.
The project health check in the CLI uses LspApi directly instead of
tool internals. iter_subclasses now yields each class once.
Introduce JetBrainsApi as the second facade implementation, exposing
all JetBrains IDE-backed operations to the REPL: find_symbol,
find_referencing_symbols, get_symbols_overview, get_type_hierarchy,
find_declaration, find_implementations, rename, move, safe_delete,
inline_symbol, run_inspections, list_inspections, debug_eval and
debug_eval_info (which provides the debug REPL usage information
otherwise obtained via the serena_info tool).
Result objects carry their rendering policy, following the LSP facade:
* JetBrainsSymbolCollection with renderers for symbol searches
(grouped JSON, falling back to identifiers) and references (falling
back to per-file counts and the total count)
* JetBrainsSymbolsOverview with the compact overview format and its
shortening ladder
* JsonObject, a new general-purpose representable for plain JSON
results with length limiting
The JetBrains tools now delegate to the API via a common JetBrainsTool
base, retaining only transport concerns (input sanitisation, the
wildcard-to-overview convenience of the find symbol tool), so that
both surfaces share one implementation. The agent adds the facade to
the REPL when the JetBrains backend is active.
serena_config imported JetBrainsPluginClient through a transitive
re-export from jetbrains_tools; it now imports it from its module.
Introduce an alternative to individual tool calls: a single tool
(serena_repl) executes Python code against an entrypoint object `s`,
which exposes Serena's functionality through facades. This lets the
LLM compose operations, filter results in code and return only what
it needs, keeping intermediate data out of the context window.
Facades (serena.facades):
* FacadeApi: base class for implementations. Member naming determines
LLM visibility: regular names are LLM-facing, a trailing underscore
marks members that are public within Serena but never exposed to the
LLM, a leading underscore is private.
* Facade: indirection over a FacadeApi instance (Facade.from_api),
holding one FacadeMethod per LLM-facing method, each of which can be
enabled or disabled independently; only enabled methods are
accessible from REPL code and included in the documentation.
* SerenaRepl/SerenaReplEntrypoint: execute code as the body of a
function (`return` defines the result; a single expression is
evaluated directly), render the result via Representable and
report errors with the line within the submitted code. Progressive
disclosure via s.info(): the tool description and s.info() list the
facades with their method names only; s.info("<facade>") and
s.info("<facade>.<method>") provide signatures together with
docstrings, never signatures alone.
* Representable/Renderer: result objects carry their rendering policy.
Output parameters are passed at retrieval time so that they are
inherited by derived results.
First facade: LspApi with find_symbol, returning an LspSymbolCollection
which renders as the familiar JSON (with grouping and progressive
shortening) while exposing the underlying symbols to code.
FindSymbolTool now delegates to LspApi, so both surfaces share one
implementation. Length limiting and JSON output were moved from Tool
into TextOutputUtils so that facades can use them.
The agent creates the REPL lazily (get_repl) and resets it on project
activation. The tool is marked beta.
Also fixes pre-existing type errors (get_tool return type, invariant
list annotations in symbol_tools, test stubs) found on the way.
bump_version could previously only create releases. It now provides two
subcommands, and the mutually exclusive --major/--minor/--patch flags (as
well as the explicit --version option) are replaced by a positional
argument, which cannot be misused:
bump_version.py release <current|major|minor|patch>
bump_version.py dev <major|minor|patch>
`dev` bumps the version to a new .dev0 version and commits it as
"Set version to vX" without creating a tag or touching the changelog. This
allows work on main to target a new minor/major version independently of a
release.
Because a .dev0 version no longer necessarily reserves the next patch
version, `release` now takes the target "current", which releases the
version reserved by the current .dev version (the usual case), whereas
major/minor/patch bump beyond it. The former special case of not
incrementing the patch version is thereby removed; `release patch` now
increments the patch version as its name suggests.
`release current` fails if the current version is not a development
version, in which case there is no reserved version to release.
The repository is licensed per component. SolidLSP (src/solidlsp,
test/solidlsp, test/resources) remains MIT-licensed and independently
reusable; the Serena application (src/serena, src/interprompt, scripts,
test/serena, docs) is licensed under GPL-3.0-or-later starting with the v2
licensing transition. The change is not retroactive: all releases and
commits up to v1.7.0 / 74c38a65 (tag mit-final) remain available under MIT.
Since MIT is GPL-compatible, a distribution combining both (such as the
serena-agent package) is as a whole subject to GPL-3.0-or-later, while the
SolidLSP files themselves stay MIT and can be extracted and used separately
under MIT terms. The distribution metadata therefore declares
GPL-3.0-or-later, with both license texts shipped alongside it.
Serena originally began under the GPL (v2) and was switched to MIT in
May 2025 following community requests. We consider that change a mistake;
the substantial changes in v2 make this the appropriate time to revert it.
We want the best version of Serena to remain free.
Changes:
* LICENSE is now the licensing overview; canonical license texts live in
LICENSES/ (MIT.txt is the previous LICENSE verbatim, GPL-3.0-or-later.txt
is the unmodified FSF text)
* pyproject.toml declares the PEP 639 license expression
"GPL-3.0-or-later" and bundles LICENSE and LICENSES/* as license files;
the deprecated MIT classifier is dropped and flake.nix declares gpl3Plus;
README has per-component license badges and a License section
* SPDX-License-Identifier headers in all Python sources under src/ and
scripts/, added by the new idempotent scripts/add_spdx_headers.py, which
gen_prompt_factory.py also uses to keep the header on the generated
module; existing third-party notices are preserved
* CLA.md: Contributor License Agreement (contributor retains copyright;
grants a perpetual, irrevocable license including relicensing under any
terms, incl. proprietary/commercial; patent grant; authority
representations), to be enforced repository-wide via cla-assistant.io
* CONTRIBUTING.md, PR template and a new docs page explain the licensing
boundary and the CLA workflow
* Apply object-oriented design
* Establish common interface via protocol LanguageServerIdLike
* Move all registration concerns to LanguageServerRegistry
Caching happened in the base implementation before subclass overrides could
post-process the result, so an override's work was either never cached or,
if it mutated in place, re-applied to cached output on every hit.
Restructure both symbol caches so that they wrap the subclass logic:
subclasses now post-process via dedicated hooks (`_request_raw_document_symbols`
and `_build_document_symbols_from_raw_symbols`), and the cached value is
the fully processed result. Cache versions are bumped where the cached
content changes as a consequence.
Dominik Jain