DEV Community: Solon Framework

Giving an AI Agent a Real Sandbox: Filesystem and Network Jail, in Java

Solon Framework — Mon, 14 Sep 2026 00:53:49 +0000

Ask a coding agent to run a build, and you have just handed a language model the ability to cat ~/.ssh/id_rsa. Prompt-level instructions like "do not read sensitive files" are not a security boundary — they are a suggestion to a stochastic process. If the agent executes commands on your machine, the only control that actually holds is the one the operating system enforces.

That is the problem Solon AI's new solon-ai-sandbox module solves. It is a Java port of Claude Code's sandbox-runtime, and it wraps agent-issued commands in real filesystem and network isolation — on macOS, Linux, and Windows.

All code below was verified against the solon-ai-sandbox source in the Solon AI 4.1.x tree.

Why not just run the agent in Docker?

Containers are the usual answer, and for a server-side agent they are the right one. But the agents people actually run interactively — the ones editing their working copy of a repo — are not in a container. They are on a laptop, in a terminal, one bash call away from everything the user can touch.

Booting a VM or a container per command is too slow for that loop, and it breaks the agent's access to the working tree you wanted it to edit. What you want is a narrow boundary: keep the agent in the project directory, let it reach the registries and package mirrors the build needs, and make everything else fail closed — without a container runtime in the picture.

solon-ai-sandbox does exactly that, using each platform's native facility:

Platform	Mechanism
macOS	`sandbox-exec` with a generated Seatbelt profile
Linux	`bubblewrap` (`bwrap`), plus `socat` for the network bridge
Windows	`srt-win.exe` with a WFP filter layer

The module depends on nothing but solon-ai-core, so pulling it in does not drag a container runtime along with it.

The entry point is one class

SandboxManager is a final class with static methods — there is one sandbox per process, and there is one place to configure it.

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-sandbox</artifactId>
    <version>${solon-ai.version}</version>
</dependency>

Initialization takes a runtime config and an optional interactive callback:

SandboxManager.initialize(config, askCallback);

And wrapping a command is a single call:

String wrapped = SandboxManager.wrapWithSandbox("git status");
Process p = Runtime.getRuntime().exec(new String[]{"/bin/bash", "-c", wrapped});

On macOS the result is a sandbox-exec -p '<seatbelt profile>' invocation; on Linux it is a bwrap invocation with the appropriate bind mounts and namespaces. Your code never branches on the platform.

Filesystem: two different policies, on purpose

Reads and writes use opposite defaults, and understanding why is the key to configuring this correctly.

Writes are allow-only. The default is deny everything. You list the paths the agent may write, and denyWrite punches holes back out of that list. The manager always adds the paths a process genuinely cannot function without — /dev/*, temp directories, and so on — so you are not fighting the OS.

Reads are deny-then-allow-back. The default is allow, because breaking every read on the machine would break the compiler, the JVM, and half of userspace. Instead you name the regions to protect, and allowRead re-opens specific paths inside them.

FilesystemConfig fs = new FilesystemConfig(
    Arrays.asList("~/.ssh", "~/.aws"),   // denyRead
    Collections.emptyList(),             // allowRead
    Arrays.asList("/tmp", "."),          // allowWrite
    Arrays.asList(".git"),               // denyWrite
    false                                // allowGitConfig
);

Read that as: the agent may write only under the current working directory and /tmp, must never write into .git, and may not read your SSH or AWS credentials even though reads are otherwise open.

Two details that matter in practice:

An empty allowWrite list is the strictest possible setting — it means no writes at all beyond the mandatory system paths.
Don't write into .git. A corrupted or maliciously rewritten Git directory is a nasty persistence vector, which is why denyWrite on .git shows up in the security defaults, and why .git/config gets its own allowGitConfig switch (default false).

Network: a proxy, not a firewall rule

Network isolation here is implemented with a local HTTP and SOCKS5 forward proxy. The sandboxed process is pointed at it via environment variables, and the module decides per request whether to let the connection through.

NetworkConfig network = new NetworkConfig(
    Arrays.asList("api.openai.com", "*.github.com"), // allowlist
    Arrays.asList("telemetry.example.com"),          // denylist
    null, null, null, null, null, null, null, null, null, null
);

Domain patterns support wildcards like *.github.com, and HostUtils normalizes IPv4, IPv6, and hostnames so that matching is not trivially bypassed by writing an address a different way.

The reason to use a proxy instead of a kernel firewall rule is live updates. The proxies read the configuration on every request, so this takes effect immediately, on already-running agent processes, with no rebind and no port change:

SandboxManager.updateConfig(newConfig);

Compare that with filesystem rules, which are not live: on macOS the rules are baked into the Seatbelt profile when the command is wrapped, and on Windows they have to be explicitly re-stamped. To change filesystem restrictions you must reset() and initialize() again. Know which knob is hot and which one requires a restart.

There is also a callback for the case where the allowlist is not the final word:

SandboxAskCallback callback = (hostPattern) -> {
    System.out.println("Allow " + hostPattern.getHost() + ":" + hostPattern.getPort() + "? [y/N]");
    return new Scanner(System.in).nextLine().trim().equalsIgnoreCase("y");
};

It fails closed: if the callback throws, or no configuration covers the request, the connection is denied.

The constructor signature changed — watch out for this

Here is a concrete trap. The module's README still shows a SandboxRuntimeConfig with 12 constructor arguments. The current source declares 13:

SandboxRuntimeConfig config = new SandboxRuntimeConfig(
    network,                       // NetworkConfig
    fs,                            // FilesystemConfig
    ignoredViolations,             // Map<String, List<String>>
    null,                          // enableWeakerNestedSandbox
    null,                          // enableWeakerNetworkIsolation
    null,                          // allowAppleEvents
    null,                          // RipgrepConfig
    null,                          // mandatoryDenySearchDepth
    null,                          // allowPty
    null,                          // SeccompConfig
    null,                          // bwrapPath
    null,                          // socatPath
    null                           // WindowsConfig  <-- the 13th
);

The trailing WindowsConfig parameter is the one the README example is missing, so code copied from it will not compile against 4.1.x. I verified this directly in SandboxRuntimeConfig.java; the code in this post is written against the source, not the README.

Windows needs a different call

wrapWithSandbox(String) returns a shell string, and on Windows it throws instead:

wrapWithSandbox() returns a shell string and is not supported on Windows. Use SandboxManager.wrapWithSandboxArgv()...

The argv variant returns { argv, env }, where env carries the full proxy environment the child needs to inherit. On macOS and Linux it still works — it just wraps the string form behind <shell> -c — so if you want one code path across all three platforms, use wrapWithSandboxArgv everywhere and spawn with { shell: false }.

Observability: violations are data, not just logs

A blocked operation is an event worth recording. SandboxViolationStore is a thread-safe, category-keyed store:

SandboxViolationStore store = new SandboxViolationStore(ignoreViolations);
store.record("network", "attempted connection to telemetry.example.com:443");

for (String category : store.getCategories()) {
    System.out.println(category + ": " + store.getViolations(category));
}

Because violations are categorized — file_read, file_write, network — a burst of network denials from a normally well-behaved agent is a signal worth alerting on. ignoreViolations suppresses known-noisy entries by substring match, which keeps the signal readable.

Before you ship this: two operational gotchas

Check dependencies at startup, and fail loudly. initialize() refuses to proceed if the platform's dependency is missing, and you should surface that rather than silently degrading to an unsandboxed run:

Platform platform = PlatformDetector.detect();
SandboxDependencyCheck deps = SandboxManager.checkDependencies();
if (deps.hasErrors()) {
    throw new IllegalStateException("Sandbox unavailable: " + deps.getErrors());
}

On Linux that means bubblewrap and socat must be installed (apt install bubblewrap socat); macOS needs nothing, since sandbox-exec ships with the OS; Windows needs srt-win.exe installed once with elevation to set up the WFP layer.

Call cleanupAfterCommand() after each command on Linux. bwrap creates empty placeholder files on the host filesystem when it protects paths that do not exist — ~/.bashrc on a fresh container, for example. They linger after the process exits. The method is a no-op on macOS, and it is also invoked from reset() and a JVM shutdown hook, but calling it in your command loop avoids accumulating junk.

The mental model

Three rules cover almost all of it:

Writes are opt-in, reads are opt-out. Configure writes as an explicit allowlist; configure reads as a short list of things worth protecting.
Network is hot, filesystem is cold. Allowlist changes apply to running processes; filesystem changes need a reset.
Fail closed, and fail visibly. Missing dependencies and unmatched callbacks should surface as errors, not as an unsandboxed fallback.

The larger point is about where the boundary lives. Once an agent can execute code, "the model was asked nicely" is not a control. solon-ai-sandbox moves that control down into the mechanism the OS already enforces — Seatbelt, bubblewrap, or the Windows Filtering Platform — and hands you a small, uniform Java API for it.

For a Java agent stack, that is the difference between a demo and something you let near a real repository.

References

Solon AI documentation: https://solon.noear.org/article/learn-solon-ai
Module source (solon-ai-sandbox), Solon AI 4.1.x tree
Claude Code sandbox-runtime (the TypeScript original this module ports)

MCP Without the Boilerplate: Solon AI's Annotation-Driven Server and Self-Healing Client

Solon Framework — Tue, 08 Sep 2026 02:23:53 +0000

If you have been following this series, you have seen how Solon AI streams chat as semantic events and how it chunks documents by meaning. This time we move from conversation plumbing to capability plumbing: how Solon AI turns ordinary Java code into MCP (Model Context Protocol) services, and how it consumes remote MCP servers without hand-writing protocol code.

All code in this post was verified against the Solon AI 4.1.x source tree (solon-ai-mcp and mcp-core modules).

Why MCP, and why in-process?

MCP standardizes how an LLM application discovers and invokes tools, reads resources, and loads prompts from an external provider. Instead of hard-coding function calls into your prompt pipeline, you point your app at an MCP endpoint — local or remote — and the capability list arrives over the wire.

Solon AI ships MCP support in two layers:

mcp-core — a self-contained protocol implementation covering MCP spec revisions from 2024-11-05 through 2025-11-25.
solon-ai-mcp — the application-facing layer: an annotation-driven server and a ToolProvider-compatible client that plugs straight into ChatModel.

The design goal is visible in the dependency direction: the protocol layer knows nothing about Solon AI, and the integration layer adds almost nothing you have to learn.

The server: one annotation per capability

Declare an endpoint class with @McpServerEndpoint, then annotate plain methods:

@McpServerEndpoint(
        mcpEndpoint = "/mcp/sse",
        heartbeatInterval = "30s")
@Component
public class McpServerTool {
    // Tip: enable the -parameters compiler flag,
    // or give every @Param an explicit name.
    @ToolMapping(description = "查询天气预报")
    public String getWeather(@Param(description = "城市位置") String location) {
        return "晴，14度";
    }
}

That is the whole server. At startup, McpPlugin scans @McpServerEndpoint classes and builds an McpServerEndpointProvider from them. Method-level providers — MethodToolProvider, MethodResourceProvider, MethodPromptProvider — extract @ToolMapping, @ResourceMapping, and @PromptMapping methods and register them with the endpoint's lifecycle. No JSON schemas to maintain by hand, no dispatch switch, no transport wiring.

Details worth knowing:

heartbeatInterval defaults to "30s" on the server side.
sseEndpoint() and messageEndpoint() are deprecated; the unified mcpEndpoint() is the way to go.
There are two hosting models: a stateful host (STREAMABLE channel) that keeps session state per client, and a stateless one (STREAMABLE_STATELESS) where every request carries everything it needs — the better fit behind load balancers.
enableOutputSchema() can turn on output schema validation for tools that need it.

The client: `McpClientProvider`

On the consuming side, one class implements ToolProvider, ResourceProvider, and PromptProvider:

McpClientProvider mcpClient = McpClientProvider.builder()
        .url("http://localhost:8081/sse")
        .build();

ChatModel chatModel = ChatModel.of(chatConfig)
        .defaultToolAdd(mcpClient)
        .build();

ChatResponse resp = chatModel
        .prompt("杭州天气和北京降雨量如何？")
        .call();

The provider is lazy: the underlying McpAsyncClient is created on first use, guarded by a lock. From then on, ChatModel treats MCP tools exactly like local function tools — the model sees them in its tool list, picks one, and Solon AI routes the invocation through callTool(name, args).

Four channels, one builder

McpChannel defines STDIO, SSE, STREAMABLE, and STREAMABLE_STATELESS. The builder picks the transport for you:

Channel	Transport	Typical use
`STDIO`	`StdioClientTransport`	Launching a local MCP binary as a subprocess
`SSE`	`WebRxSseClientTransport`	Classic HTTP + server-sent events
`STREAMABLE`	`WebRxStreamableHttpTransport`	Modern streamable HTTP, stateful session
`STREAMABLE_STATELESS`	`WebRxStreamableHttpTransport`	Stateless streamable HTTP, LB-friendly

For per-call granularity instead of defaults, push the tool list into the prompt options:

chatModel.prompt("今天杭州的天气情况？")
        .options(options -> options.toolAdd(mcpClient.getTools()))
        .stream()
        .filter(e -> e.is(ChatEventType.TEXT_DELTA) && e.hasText())
        .map(ChatEvent::getText);

Note how this composes with the ChatEvent streaming API from the first post in this series — MCP tools and semantic events are orthogonal layers.

Self-healing connections

Network transport code fails in boring, repetitive ways. McpClientProvider centralizes the retry:

public <T> T executeWithRetry(Function<McpAsyncClient, Mono<T>> action) {
    try {
        return action.apply(getClient()).block();
    } catch (Throwable ex) {
        if (isTransportError(ex)) {
            this.reset();                                 // drop the broken client
            return action.apply(getClient()).block();     // reconnect, retry once
        }
        throw ex;
    }
}

isTransportError matches McpTransportException, timeouts, connection refusals, and friends. Protocol-level errors (a tool that returned an error, for example) propagate untouched — retrying those would be wrong.

If you enable heartbeats, a failed beat doubles the backoff interval on each retry, capped at 10 minutes. Intervals under 5 seconds are rejected outright. And note the asymmetry: the server sends heartbeats every 30s by default, while the client opts in explicitly — a deliberate choice to keep the client quiet unless you ask.

Caching and change notification

Listing tools, resources, and prompts over MCP is a round trip you do not want on every prompt. The client caches these lists locally for 30 seconds by default (cacheSeconds). When the server emits a change notification, the matching cache entry is invalidated — the next listing goes back over the wire. The notification clears the cache; it does not push the new list. Subtle, but it is the difference between "eventually fresh" and "push-updated," and it keeps the client simple.

Tool allow-lists and deny-lists

allowedTools and disallowedTools filter what the client exposes. Filtering applies the allow-list first, then the deny-list — so a tool must pass both gates to reach your model. Handy for exposing a curated subset of a large third-party MCP server.

Configuration-driven wiring

Instead of building clients in code, bind them from configuration under the solon.ai.mcp.client.<name> prefix:

@Bean
public McpClientProvider clientWrapper(
        @Inject("${solon.ai.mcp.client.demo}") McpClientProvider client) {
    return client;
}

There is also McpClientProviders.fromMcpServers(uri) for loading a whole mcpServers-style map at once — useful when your tool landscape lives in config rather than Java.

Gotchas I hit while reading the source

The Javadoc lies a little. The class-level example in McpClientProvider shows .apiUrl(...) and .defaultToolsAdd(...); the actual builder method is .url(...), and the demo code uses defaultToolAdd. Trust the code, not the comment — I have reported the drift.
-parameters matters. Without the compiler flag, parameter names vanish from bytecode, and @Param needs an explicit name.
Heartbeat defaults are asymmetric. Server: 30s on. Client: off. Do not assume both ends keep-alive the same way.
Stateless is a mode, not a transport. STREAMABLE_STATELESS uses the same HTTP transport; the difference is in session handling on the server host.

When does this matter?

The annotation server shines when you have an existing Solon service full of business methods that AI agents suddenly need to call. The client shines when you want to compose capabilities across process boundaries — a weather server here, a database MCP there, all flowing into one ChatModel with retries and caching you did not write.

Together with the streaming events and semantic splitting covered earlier, that completes a picture worth remembering: Solon AI treats MCP not as a bolt-on integration but as another expression of the same builder-and-provider abstractions the rest of the framework runs on.

References

Solon AI repository and docs: https://solon.noear.org/article/learn-solon-ai
Model Context Protocol specification: https://modelcontextprotocol.io
Earlier in this series: Semantic Chat Events, SemanticSplitter

Verified against the Solon AI 4.1.x source tree; class and method names reflect that version.

Chunk by Meaning, Not Just Size: A Deep Dive into Solon AI's SemanticSplitter

Solon Framework — Mon, 07 Sep 2026 06:07:19 +0000

Chunk by Meaning, Not Just Size: A Deep Dive into Solon AI’s SemanticSplitter

RAG quality is often discussed as if the only question were which vector database to choose. In practice, the shape of the text entering that database matters just as much. If one chunk mixes a refund rule, a shipping exception, and an account-security note, a strong embedding model cannot fully repair the damaged boundary.

Solon AI’s SemanticSplitter offers a different trade-off from regex- and token-based splitting: it uses an embedding model to look for likely topic boundaries before applying a token-size fallback.

This article examines what the implementation actually does in Solon AI v4.1.0, where it fits in the RAG pipeline, and which assumptions an application should still validate.

The splitter is an ingestion-stage component

Solon’s RAG documentation separates the main stages clearly:

DocumentLoader -> DocumentSplitter -> RepositoryStorable.save(...)

DocumentLoader turns a file or other source into Document objects. A DocumentSplitter can then turn large documents into smaller retrieval units. The resulting documents are finally stored in a Repository.

SemanticSplitter belongs to the middle stage. It does not query a vector database and it does not decide which documents to retrieve at runtime. Its job is to decide where the boundaries of the documents should be before indexing.

The class is:

org.noear.solon.ai.rag.splitter.SemanticSplitter

and it implements the same DocumentSplitter abstraction used by other Solon AI splitters.

What the default constructor configures

The simplest construction is:

SemanticSplitter splitter = new SemanticSplitter(embeddingModel);

The source defines these defaults:

Setting	Default	Meaning
`similarityThreshold`	`0.5`	A lower similarity marks a candidate boundary
`maxChunkTokenSize`	`512`	Target maximum size for a semantic group
`similarityWindow`	`3`	Number of preceding sentences used as context
`minSentencesPerChunk`	`1`	Minimum distance between accepted boundaries
`delimiters`	`ALL_COMMON_DELIM`	Common English, Chinese, and newline delimiters

These are defaults, not universal production settings. Similarity distributions vary between embedding models, languages, and corpora. A threshold that is useful for one model can be too aggressive or too conservative for another.

The algorithm is a sliding-window comparison

The implementation does not embed the entire document once and then run a generic clustering algorithm. Its flow is more specific:

raw text
  -> sentence-like segments
  -> sliding context windows
  -> embeddings for windows and following sentences
  -> cosine similarities
  -> threshold-based boundaries
  -> token-size fallback
  -> new Documents with inherited metadata

1. Sentence-like segmentation

The splitter scans the text using the configured delimiters. The delimiter remains attached to the preceding segment. The built-in common set includes:

SemanticSplitter.ALL_COMMON_DELIM

which covers ., !, ?, Chinese 。, ！, ？, ；, and newlines.

This is deliberately simpler than a full natural-language sentence parser. If a document uses unusual punctuation or has long sections without the configured delimiters, the resulting segments will reflect that.

2. Build a context window

For each position, the splitter concatenates the next similarityWindow sentences into a window. With the default window of three, the comparison looks conceptually like this:

[sentence 0 + sentence 1 + sentence 2]  vs  [sentence 3]
[sentence 1 + sentence 2 + sentence 3]  vs  [sentence 4]
[sentence 2 + sentence 3 + sentence 4]  vs  [sentence 5]

Each side is embedded. The cosine similarity between the window and the following sentence becomes the signal for that position.

A low score suggests that the next sentence may represent a topic transition. It is a candidate boundary, not a semantic truth guarantee.

3. Apply the threshold

The source uses the direction below:

if (similarities[i] < similarityThreshold) {
    // candidate split
}

This direction matters. Holding the text, model, and other parameters constant, increasing the threshold makes it easier for a position to fall below the threshold, so it will usually create more candidate boundaries. Lowering the threshold usually keeps larger groups together.

The result is not a simple linear knob. The final chunks also depend on the embedding model, the window size, the minimum-sentence rule, and the token fallback.

4. Enforce a token-size fallback

After semantic groups are created, the splitter counts tokens using its configured jtokkit encoding. If a group is over maxChunkTokenSize, it allocates sentences into smaller groups until the group would exceed the limit.

That makes the token limit a second-stage guardrail, not the primary boundary detector.

There is an important edge case: the fallback only moves whole sentences. If one individual sentence is already larger than the configured maximum, it can still appear as an oversized output chunk. Also, very short documents with no more than similarityWindow segments are returned as one document before the normal embedding and token fallback path runs.

So the safe statement is:

SemanticSplitter applies a token-size fallback to oversized semantic groups, but applications should still validate final chunk sizes for short documents and individually oversized sentences.

Embedding cost is part of the design

Regex splitting and token splitting can be performed locally. Semantic splitting calls the configured EmbeddingModel.

For a document with N segments and a window size of W, the normal path builds approximately:

N - W window texts
N - W following-sentence texts
2 * (N - W) embedding inputs

The inputs are sent in batches according to embeddingModel.batchSize(). The current implementation also requests:

.options(o -> o.dimensions(512))

That detail deserves operational attention. The selected embedding provider must support the requested dimension behavior, and the application should measure whether the chosen dimension preserves acceptable boundary quality for its corpus. Do not assume that every provider interprets dimensionality options identically.

The practical cost model is therefore different:

Splitter	Boundary signal	Typical cost	Main risk
`RegexTextSplitter`	Document structure	Local CPU	Structure may be inconsistent
`TokenSizeTextSplitter`	Token count	Local CPU	A chunk can cross topic boundaries
`SemanticSplitter`	Embedding similarity	Embedding calls plus CPU	Cost and thresholds need validation

This is not a ranking in which the semantic splitter always wins. It is a choice between different failure modes.

Metadata is preserved, but chunk identity is not invented

When the splitter creates a new Document, it passes the original metadata through:

new Document(content, metadata)

That is useful for filters such as:

source file;
department;
tenant;
document version;
access scope.

However, the splitter does not automatically add a chunk number, parent-document ID, page number, character offsets, or neighboring-chunk links. If those fields are needed for citation, deletion, re-indexing, or audit trails, add them in the application’s ingestion layer rather than assuming they are framework-generated.

A production ingestion pipeline might therefore enrich the metadata after splitting:

List<Document> chunks = splitter.split(loadedDocuments);

for (int i = 0; i < chunks.size(); i++) {
    // Add application-owned tracking fields here:
    // chunkIndex, sourceId, pageNumber, version, and so on.
}

repository.save(chunks);

The exact metadata API depends on the application’s ownership model. The important design point is that chunk tracking is an application responsibility unless the loader already supplies the required fields.

How to evaluate it instead of guessing

Semantic chunking should be evaluated with the same discipline as a retrieval model. A useful experiment can use one mixed-topic corpus containing, for example:

refund rules;
shipping compensation;
account-security requirements;
similar vocabulary across all three sections.

Compare at least these measurements:

number of produced chunks;
average and P95 token count;
number of chunks crossing a known section boundary;
embedding request count;
ingestion latency;
Recall@K on a fixed question set;
retrieved-context token count;
whether the final answer cites the correct section.

A small parameter sweep is also more informative than copying defaults blindly:

similarityThreshold: 0.35 / 0.50 / 0.65
similarityWindow:    1 / 3 / 5
maxChunkTokenSize:   256 / 512 / 1024

Report results with the corpus, embedding model, parameter values, and measurement method. Without those details, a claim such as “semantic splitting improves accuracy” is too broad to be reliable.

Where Agent RAG fits

Solon AI has separate concepts for ingestion and runtime retrieval. A useful mental model is:

SemanticSplitter
      -> better-shaped Documents
      -> Repository
      -> RepositoryTool
      -> ReActAgent

These components answer different questions:

SemanticSplitter: where should the knowledge be divided?
Repository: where are the indexed documents stored and searched?
RepositoryTool: how can retrieval be exposed as a tool?
ReActAgent: when should the agent search, and whether it should search again?

Improving chunk boundaries can help the retrieval layer, but it does not turn the splitter into an agent. Conversely, an agent cannot reliably compensate for every bad ingestion boundary. Treat the ingestion strategy and runtime strategy as separate, measurable layers.

A practical decision guide

Use a structure-based splitter when:

headings and paragraphs are reliable;
indexing cost must be minimal;
deterministic boundaries are important;
you need straightforward debugging.

Use a token splitter when:

model input limits are the dominant constraint;
the corpus has weak structure;
you want predictable chunk sizes;
the retrieval quality trade-off is acceptable.

Evaluate SemanticSplitter when:

the corpus contains frequent topic transitions inside long sections;
structural delimiters are not enough;
you can afford embedding work during ingestion;
you have a representative retrieval benchmark.

A hybrid pipeline can also be reasonable, but its order and benefit should be tested on the target corpus rather than declared as a universal best practice.

Closing thoughts

SemanticSplitter is interesting precisely because it is not magic. It is a concrete algorithm with visible costs and boundaries:

sentence-like segmentation first;
sliding-window embeddings;
cosine similarity as a boundary signal;
threshold-based grouping;
token-size fallback;
metadata inheritance;
no automatic chunk identity model.

That makes it possible to reason about, benchmark, and adapt. In a Solon AI RAG pipeline, the best splitter is not the one with the most sophisticated name. It is the one whose boundary behavior, embedding cost, and retrieval results are understood on your own documents.

Sources

Beyond Token Streaming: Solon AI 4.1's Semantic Chat Events

Solon Framework — Mon, 07 Sep 2026 04:30:29 +0000

Streaming an LLM response looks simple until the response contains more than text.

Depending on the provider, a modern stream may include reasoning fragments, tool-call arguments, citations, media updates, safety decisions, usage snapshots, status messages, and errors over the same connection. Treating every frame as “another partial response” pushes provider-specific parsing into the UI and makes it difficult to distinguish a transient fragment from the final answer.

Solon AI 4.1 addresses that problem with a semantic event stream:

Before 4.1:       Flux<ChatResponse>
Starting with 4.1: Flux<ChatEvent>

The change is more than a generic type replacement. ChatEvent represents what is happening while a response is in flight. ChatResponse represents an aggregated result. The distinction gives application code a vocabulary for text, reasoning, tools, lifecycle, usage, and failure without requiring it to understand every provider's raw SSE dialect.

This article builds on the official streaming event guide and checks the behavior against the Solon AI 4.1 source and core tests. One important qualification: the event API is marked @Preview("4.1") in the current source, so treat it as a preview contract that may evolve in future releases.

`call()` and `stream()` now answer different questions

The synchronous API still asks for the completed answer:

ChatResponse response = chatModel.prompt("Explain semantic streaming").call();
String text = response.getText();

The streaming API asks to observe the response lifecycle:

Flux<ChatEvent> events = chatModel
        .prompt("Explain semantic streaming")
        .stream();

That difference prevents an intermediate frame from pretending to be a complete response.

For a text-only projection, select the exact semantic event you need:

Flux<String> text = chatModel.prompt(message).stream()
        .filter(event -> event.is(ChatEventType.TEXT_DELTA)
                && event.hasText())
        .map(ChatEvent::getText);

Two details are intentional:

isDelta() is too broad for a typewriter projection. It also covers reasoning, tool arguments, media partials, and refusal deltas.
getText() is nullable. hasText() keeps a Reactor map from receiving a null result.

This is the first practical rule of the new model: project by meaning, not by transport shape.

Nine groups provide the current routing layer

The current source defines 31 event types organized into nine groups:

Group	What it represents	Representative events
`LIFECYCLE`	Whole-response state	`RESPONSE_START`, `STATUS`, `HEARTBEAT`, `RESPONSE_END`, `ABORT`
`STEP`	One model round	`STEP_START`, `STEP_END`
`TEXT`	User-visible answer text	`TEXT_START`, `TEXT_DELTA`, `TEXT_END`
`THINKING`	Reasoning-related output	`THINKING_START`, `THINKING_DELTA`, `THINKING_END`
`TOOL_CALL`	Client-executed tools	`TOOL_CALL_START`, `TOOL_CALL_ARGS_DELTA`, `TOOL_CALL_END`, `TOOL_RESULT`
`SERVER_TOOL`	Provider-side tools	`SERVER_TOOL_START`, `SERVER_TOOL_ARGS_DELTA`, `SERVER_TOOL_RESULT`
`MEDIA`	Citations and generated media	`CITATION`, `MEDIA_PARTIAL`, `MEDIA_DONE`
`SAFETY`	Refusals and filtering	`REFUSAL_DELTA`, `CONTENT_FILTER`
`META`	Usage, errors, raw and custom data	`USAGE`, `ERROR`, `RAW`, `CUSTOM`

These groups are useful when building a generic router. Specific event types can evolve while the application keeps stable top-level destinations:

void route(ChatEvent event) {
    switch (event.getGroup()) {
        case TEXT:
            if (event.is(ChatEventType.TEXT_DELTA) && event.hasText()) {
                ui.appendAnswer(event.getText());
            }
            break;
        case THINKING:
            if (event.is(ChatEventType.THINKING_DELTA) && event.hasText()) {
                ui.appendReasoning(event.getText());
            }
            break;
        case TOOL_CALL:
            toolPanel.accept(event);
            break;
        case SERVER_TOOL:
            serverToolPanel.accept(event);
            break;
        case MEDIA:
            mediaPanel.accept(event);
            break;
        case SAFETY:
            safetyPanel.accept(event);
            break;
        case STEP:
            timeline.accept(event);
            break;
        case LIFECYCLE:
            lifecycle.accept(event);
            break;
        case META:
            diagnostics.accept(event);
            break;
        default:
            log.debug("Unhandled event type: {}", event.getType());
    }
}

Keeping a default branch is still sensible for preview APIs and future versions.

An event-phase `END` is not necessarily the end of the stream

Events also have phases such as START, DELTA, END, and NONE. The word END is local to an event scope.

For example:

TEXT_END closes a text block;
THINKING_END closes a reasoning block;
TOOL_CALL_END closes one tool call;
STEP_END closes one model round;
RESPONSE_END closes a successful response lifecycle.

Use event.isTerminal() when you mean a whole-stream semantic terminal. In the current enum, it is true for:

RESPONSE_END
ABORT
ERROR

Do not replace that check with event.getPhase() == END. ERROR is terminal but has phase NONE, while several local boundary events have phase END without terminating the response.

Recover the final response from `RESPONSE_END`

If a caller needs the final aggregate while using the streaming path, it should select RESPONSE_END first:

ChatResponse response = chatModel.prompt(query).stream()
        .filter(event -> event.is(ChatEventType.RESPONSE_END))
        .map(ChatEvent::getResponse)
        .blockFirst();

The asynchronous form can expose the first matching terminal response as a Mono<ChatResponse>:

Mono<ChatResponse> response = chatModel.prompt(query).stream()
        .filter(event -> event.is(ChatEventType.RESPONSE_END))
        .map(ChatEvent::getResponse)
        .next();

Calling blockFirst() on the unfiltered stream is a classic migration mistake. The first event is normally RESPONSE_START, not the final answer.

The caller does not need to concatenate every TEXT_DELTA to reconstruct the official final response. Solon AI accumulates the response internally and attaches the aggregate to the terminal event. Local concatenation can still be useful for immediate rendering, but it should be treated as a UI projection rather than the source of truth for tool calls, usage, and the complete assistant message.

The normalizer creates consistent stateful event boundaries

Provider stream formats differ in how consistently they expose boundaries. A provider may send a text delta without an explicit text-start frame. Tool-call fragments may omit a stable identifier after the first frame. Reasoning and answer text may alternate. A stream can terminate while a content block is still open.

ChatEventNormalizer sits between parsed provider semantics and the subscriber. Its job is to make event boundaries usable:

TEXT_START -> TEXT_DELTA* -> TEXT_END
THINKING_START -> THINKING_DELTA* -> THINKING_END
TOOL_CALL_START -> TOOL_CALL_ARGS_DELTA* -> TOOL_CALL_END

For text and thinking blocks, the normalizer uses stricter tracking:

a bare delta can cause a matching start to be synthesized;
duplicate starts for the same block are dropped;
an unmatched end is dropped;
switching between thinking and text closes the previously open block;
completion closes remaining open blocks.

Tool calls use a deliberately looser policy. An arguments delta can synthesize a start when no call is open, and an unmatched end is preserved. This is not a malformed-stream validator. It is a compatibility layer for providers whose later argument fragments do not repeat a complete tool-call ID.

That difference is important when writing application code. The normalizer provides compatibility-oriented boundary completion, not strict tool-call identity validation. Use normalized events for rendering and correlation, but read the complete ToolCall objects from a completed step or final response rather than assuming that one argument delta contains valid JSON.

Tool execution introduces steps

An automatic tool workflow is not a single model round. It commonly looks like this:

RESPONSE_START
  STEP_START (0)
    TOOL_CALL_START
    TOOL_CALL_ARGS_DELTA ...
    TOOL_CALL_END
    TOOL_RESULT
  STEP_END (0)
  STEP_START (1)
    TEXT_START
    TEXT_DELTA ...
    TEXT_END
  STEP_END (1)
RESPONSE_END

The response lifecycle remains one unit, while each provider request becomes a step. The current implementation starts step numbering at zero and increments it for recursive model calls.

A normally completed STEP_END event carries the terminal snapshot and usage for that step. RESPONSE_END carries the whole successful response aggregate and cross-step usage total. This lets an observability system answer two different questions:

What did this model round produce and cost?
What did the complete tool-assisted response produce and cost?

Tool argument fragments may be interleaved when multiple calls are in flight. Correlate them by toolCallId when one is available; do not build a parser that assumes all fragments for one call arrive as a single contiguous JSON document.

Usage is a two-level aggregation problem

Usage data is easy to overcount.

Within one provider step, usage frames are commonly cumulative snapshots. Adding every frame would count the same tokens repeatedly. Across steps, however, each step is a separate model request, so completed-step totals need to be added.

Solon AI's stream session reflects that distinction:

within a step: keep/merge the provider snapshot
across steps:  add completed-step usage

Consequently:

STEP_END.getUsage() describes the current completed step;
RESPONSE_END.getUsage() describes the accumulated successful response;
a standalone USAGE event is an observation, not an instruction to blindly add every value it contains.

The source also preserves provider usage metadata across steps. Numeric fields such as token and server-tool counts are accumulated, while label-like values use different merge behavior. The larger lesson is portable: billing telemetry needs a scope model, not just a counter.

Errors, aborts, and cancellation are different

A production subscriber must distinguish three mechanisms.

`ERROR` and Reactor `onError`

For failures that enter the main reactive error path, Solon AI attempts to expose an ERROR event before terminating the Reactor stream with an error. The two channels serve different purposes:

the event channel can carry semantic context such as a previously completed response snapshot or accumulated usage;
Reactor onError drives retry, fallback, timeout, and recovery operators.

They describe one failure, not two failures. Also, do not assume that ERROR.getResponse() contains the partially streamed text from the currently failing step. The aggregate may contain only previously completed steps, or it may be null when the first step fails early.

A custom event filter can suppress a META event such as ERROR, while Reactor onError still arrives. Keep an error consumer even if the UI also handles error events:

chatModel.prompt(query).stream().subscribe(
        this::route,
        error -> recoverOrReport(error),
        () -> markTransportComplete());

`ABORT`

ABORT is an upstream semantic event. It is not the same thing as the subscriber cancelling its subscription. Application code can route it as a lifecycle signal, but should not infer Reactor cancellation from it.

Reactor cancellation

Operators such as take(...) may cancel the subscription. Once cancellation occurs, the downstream cannot expect extra events. In particular, it should not wait for synthetic TEXT_END, STEP_END, ABORT, or RESPONSE_END events after it has cancelled.

Cleanup belongs in Reactor lifecycle hooks such as doFinally, not in a handler that assumes every path ends with RESPONSE_END:

chatModel.prompt(query).stream()
        .doFinally(signal -> releaseUiResources(signal))
        .subscribe(this::route, this::recoverOrReport);

Event filtering is delivery policy, not aggregation policy

The default filter rejects high-volume HEARTBEAT and unmodeled RAW events. Diagnostic or gateway code can request more:

chatModel.prompt(query)
        .eventFilter(ChatEventFilter.all())
        .stream();

Or it can extend the default policy:

ChatEventFilter filter = ChatEventFilter.DEFAULT.or(
        ChatEventFilter.of(ChatEventType.RAW));

chatModel.prompt(query)
        .eventFilter(filter)
        .stream();

There is a subtle source-level detail worth knowing. Runtime filtering is guarded so lifecycle and step groups survive a non-null custom filter. Therefore, this:

.eventFilter(ChatEventFilter.of(ChatEventType.TEXT_DELTA))

does not mean the subscriber will receive only text deltas. Lifecycle and step events remain available for aggregation and boundaries. In the current preview implementation, the interaction between the default filter, guarded custom filters, and HEARTBEAT is nuanced because heartbeat itself belongs to the lifecycle group.

The robust approach is:

use eventFilter to control broad delivery volume;
still use an exact downstream filter when projecting one semantic channel;
use ChatEventFilter.all() only when raw protocol visibility is genuinely needed.

Filtering happens after Solon AI's internal normalization and aggregation. Hiding an event from a subscriber does not undo the internal final response.

A provider dialect translates frames; it should not duplicate semantics

A custom provider integration implements the streaming parser entry point:

void parseResponseJson(ChatStreamContext ctx, String respJson);

Conceptually, there are two output paths:

Put primary content such as answer text, reasoning, and client tool calls into the accumulator so the core can generate standard events and aggregates.
Emit semantic events directly for provider capabilities such as citations, status, server-side tools, or specialized media.

The following is illustrative pseudocode; readProviderResponseId, readTextDelta, readCitation, and buildCitation are provider-specific helpers:

@Override
public void parseResponseJson(ChatStreamContext ctx, String json) {
    ctx.setProviderResponseId(readProviderResponseId(json));

    String text = readTextDelta(json);
    if (text != null && !text.isEmpty()) {
        ctx.getAccumulator().addContentItem(
                new AssistantMessage(text));
    }

    String citationUrl = readCitation(json);
    if (citationUrl != null) {
        ctx.emit(ctx.event(ChatEventType.CITATION)
                .block(buildCitation(citationUrl))
                .build());
    }
}

Do not send the same semantic payload through both paths. If text is added to the accumulator and also emitted as a text delta, consumers can see duplicate deltas and the aggregate can be corrupted.

The unified layer is valuable precisely because provider frames and application events are not one-to-one. A single frame may update usage and text; one semantic tool call may span many frames. The dialect should translate provider protocol, while the core owns the cross-provider event contract.

A practical migration checklist

When moving pre-4.1 streaming code to the preview event model:

Replace Flux<ChatResponse> declarations with Flux<ChatEvent>.
Render answer text only from TEXT_DELTA plus hasText().
Route reasoning separately from answer text.
Do not use isDelta() as a synonym for user-visible text.
Select RESPONSE_END before calling blockFirst() or next() for the final response.
Read completed tool calls from STEP_END or RESPONSE_END, not from one arguments fragment.
Treat STEP_END usage and RESPONSE_END usage as different scopes.
Keep Reactor error handling even when consuming ERROR events.
Treat cancellation as a transport/control action, not as ABORT.
Revisit custom dialects for the parseResponseJson(ChatStreamContext, String) contract.
Re-check the exact 4.1 preview API before upgrading future versions.

What the tests establish

The core source contains focused tests for the event model. I ran these three deterministic suites against the reviewed checkout:

ChatEventNormalizerTest       20 tests
ChatEventFilterTest            6 tests
ChatStreamSessionUsageTest     9 tests
---------------------------------------
Total                         35 tests

Result:

Tests run: 35, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

They provide a useful regression net for boundary normalization, filter composition, and cross-step usage aggregation. They do not prove every arbitrary event sequence, every provider's behavior, deep immutability of every payload, or every cancellation race. Provider capabilities also differ: an application must not expect every dialect to emit reasoning, citations, media, safety, server-tool, or usage events.

The architectural payoff

The most useful part of Solon AI 4.1's streaming redesign is not the number of event types. It is the separation of responsibilities:

provider SSE / JSON frames
          ↓
provider dialect parsing
          ↓
semantic accumulation and event emission
          ↓
boundary normalization
          ↓
application routing and protocol adapters

A UI can focus on rendering. An agent can focus on tool steps. An observability layer can focus on usage and failure. A gateway can opt into raw events without forcing ordinary consumers to pay that cost.

Token streaming answers, “What bytes arrived next?” Semantic streaming answers, “What happened next?” For applications that combine reasoning, tools, citations, safety, and multiple provider calls, the semantic model is generally easier to extend.

What SolonCode's Profile Backup Really Protects

Solon Framework — Sun, 06 Sep 2026 06:25:32 +0000

A configuration backup is not automatically a secure backup. In an AI coding environment, the archive may contain model endpoints, tool permissions, mount definitions, local instructions, memories, scripts, and visual themes. It may also contain credentials, even when its interface says that secrets are excluded.

SolonCode's Profile backup feature is a useful case study because the implementation is small enough to read end to end. It defines a portable ZIP format, separates settings from directory assets, provides a preview step, protects some settings values by default, and adds limits against oversized uploads and excessive decompression. At the same time, it deliberately stops short of encryption, authenticity, transactional restore, and general-purpose secret discovery.

That combination is more interesting than a feature tour. It shows how a migration tool can establish practical boundaries without pretending to be a vault or a disaster-recovery system. This article reads the implementation as an engineering design: what it includes, what it does when restoring, and what operators must still do themselves.

Start with the asset model

The service exposes six selectable backup keys:

settings
skills
agents
commands
memory
skins

The wording “six asset types” is convenient, but the filesystem model is more precise: one configuration item plus five directory-based asset collections. The source of truth is ProfileService.java, especially buildManifest(), exportZip(), and importCommit(). The HTTP allow-list is repeated in ProfileSettingsController.java as VALID_KEYS.

The default manifest marks settings, skills, agents, commands, and memory as checked. Skins are listed but not checked by default. That distinction matters: a user can migrate the visual layer, but it is not silently included in the default selection shown by the manifest/UI path.

The archive layout is intentionally simple:

manifest.json
settings/global.json
assets/skills/**
assets/agents/**
assets/commands/**
assets/memory/**
assets/skins/**

Only selected keys are written. Settings are not copied as an arbitrary byte-for-byte file. Instead, the current AgentSettings object is serialized and filtered to an allow-list of top-level groups. Directory assets are traversed and copied into their corresponding archive prefixes.

This is a good portability boundary. A consumer does not need to understand the whole SolonCode home directory. It can reason about a manifest, one settings fragment, and five known asset roots. It also leaves room for future schema versions without making the first format dependent on every incidental file in a user's home directory.

Schema versioning is a gate, not authenticity

The archive declares schemaVersion: 1. The exporter writes the value into manifest.json; both preview and commit require a manifest and call requireSchemaVersion().

The importer accepts a positive version no greater than the implementation's current version. A missing, non-positive, or higher version is rejected. Rejecting a future version is preferable to silently interpreting an incompatible structure as if it were known.

But schema validation should not be confused with content validation or trust validation. The implementation does not verify that the manifest's item list exactly matches the ZIP entries. It does not use a manifest hash to prove that files were not changed after export. It does not use a signature to authenticate the producer. It does not establish that a package came from a particular person, machine, or release.

That is a useful general lesson for portable formats: version metadata answers “which structure should I parse?” It does not answer “who produced this?” or “has this package been tampered with?” Those are separate protocol properties.

Settings are filtered by top-level group

The settings fragment is limited to these ten top-level groups:

general
permission
loop
defaultModel
models
providers
mountPools
mcpServers
apiServers
lspServers

The filter is implemented by pickSettingsGroups() in ProfileService.java. Unknown or otherwise unlisted top-level content does not become part of the exported settings fragment. This makes the archive more intentional than a raw dump of an object graph.

The restore operation has an important, sometimes surprising, matching rule. importSettingsFile() iterates through the same group list and executes the equivalent of:

current.set(group, fragment.get(group));

When a group is present, the group is replaced as a whole. This is merge-by-group, not merge-by-entry. If the archive contains a models object, the current models group is replaced by the archived models object; it is not merged model by model. If the archive does not contain mcpServers, the current group remains untouched.

This is a coherent design for a user-selected migration tool. It makes selection meaningful and avoids a vague recursive merge policy. It also creates an operational requirement: review the preview carefully before importing a group such as models, providers, mountPools, or lspServers. A group-level replacement can remove entries that exist in the current group but not in the archive.

The service does create a manual recovery point before changing an existing settings file. If the current file exists, it is copied to a sibling named like:

settings.json.bak-YYYYMMDDHHMMSS

The result includes a warning naming that backup. This is valuable, but it is not an automatic rollback mechanism. The backup is for settings.json; it does not snapshot the five asset directories. The new settings content is written with Files.write() inside the profile service rather than through the atomic temporary-file-and-move path used elsewhere by settings persistence.

“Secrets excluded” has a narrow meaning

The default export passes includeSecrets=false. The implementation then recursively walks the settings JSON and masks only six exact, case-sensitive field names:

apiKey
api_key
webAuthPass
webAuthUser
dbPassword
ldapAdminPassword

A value is replaced only when the matching field's value is a string. The replacement marker is:

__MASKED__

This is not a generic password detector. A field called token, secret, password, accessToken, or clientSecret is not automatically recognized. A differently capitalized field is not recognized. A non-string value is not replaced by this branch. The safe wording is therefore “six exact settings field names are masked,” not “all secrets are removed.”

The masking routine does recurse through objects and arrays, which means a matching name can be found below the top level. That improves coverage for nested model or server configuration. It does not change the name-based nature of the policy.

There is a second boundary that is even more important: assets are not scanned. addAssetDir() copies files from skills, agents, commands, memory, and skins directly into the ZIP. It does not call maskSecrets(). It does not search for .env files, token patterns, passwords, or the six field names inside text files.

As a result, a default export can still contain a credential embedded in a skill instruction, an agent configuration, a command script, a memory note, or a skin asset. The masked flag attached to the settings manifest item describes the settings fragment; it does not certify that the complete archive is secret-free.

This is a strong example of why security documentation must name the protected surface. “Default secret masking” sounds broad until the implementation is read. “Default masking of six exact string field names in settings JSON; directory assets are copied without scanning” is less promotional and much more useful.

Explicit plaintext export is a deliberate risk switch

includeSecrets is exposed by the export controller and defaults to false. If an operator explicitly sets it to true, the settings fragment retains the matching values in plaintext. The manifest records that choice, but the import path does not turn it into an additional trust or cryptographic policy.

There is no ZIP encryption, no password-based key derivation, and no secret-specific encryption layer. Therefore an includeSecrets=true archive should be treated as a credential bundle. It should not be committed to a source repository, attached to a public issue, placed in a shared chat, or stored on an untrusted file share.

Even a default masked archive deserves review because the five directory asset types are not scanned. If the intended migration includes secrets, a better operational pattern is to keep the archive non-secret and provision credentials separately through the destination environment. If plaintext export is unavoidable, restrict access, shorten retention, and rotate exposed credentials when the transfer is complete.

Preview and commit are separate uploads

The web controller exposes two POST endpoints:

/web/settings/profile/import/parse
/web/settings/profile/import/commit

Both require a multipart file. Both read the complete stream into memory. Both independently invoke the profile service. The preview endpoint unpacks into a temporary directory, checks the manifest and schema, calculates settings group information, and counts new versus overwritable asset files. It does not write the target settings or asset directories.

The commit endpoint receives another upload, creates another temporary directory, unpacks again, validates again, then applies the selected settings and assets.

This means the preview result is not a server-side handle to an immutable package. There is no persisted review token, no archive hash comparison, and no server-held staging directory reused by commit. A user can preview archive A and submit archive B. The selected keys can also differ between the requests.

The two-step UI is still useful as a human workflow, but its protocol meaning must be stated accurately: preview is an inspection operation, not a cryptographic binding between the reviewed bytes and the committed bytes. If “what I reviewed is exactly what I commit” is a requirement, the protocol needs an archive digest or a server-side staged object with an expiring commit token.

Resource limits help, but they are not a complete ZIP policy

The controller limits each uploaded compressed stream to:

64 * 1024 * 1024

That is 64 MiB. The check is in ProfileSettingsController.readAll() and applies independently to the parse and commit uploads. The exporter itself builds a complete ZIP in memory and does not apply this same output limit.

During extraction, ProfileService.unzipSafely() counts bytes actually written across entries. If the cumulative uncompressed output exceeds:

256 * 1024 * 1024

that is 256 MiB, extraction stops with an error. This provides a useful defense against an archive whose compressed size is small but whose expanded output is large.

There are important omissions. The code does not enforce a maximum number of entries. It does not enforce a compression-ratio limit. It does not enforce a real per-file uncompressed threshold. A local variable named written is incremented, and a comment refers to limiting one file, but no comparison against a per-file limit exists. The actual implemented byte defense is cumulative, not per-entry.

The importer also skips, rather than rejects, entries whose names contain .., and applies a normalized path containment check. This provides basic Zip Slip protection for the temporary extraction directory. It is not a complete malicious archive policy. There is no duplicate-entry uniqueness check, no signature verification, and no complete trust decision for packages from unknown sources.

Both parse and commit attempt recursive cleanup in a finally block. The temporary directory prefixes are different: soloncode-profile-unpack- for preview and soloncode-profile-import- for commit. This is good lifecycle hygiene, but cleanup can itself encounter I/O errors, and the existing service tests do not assert that successful and failing paths leave no temporary directories behind.

Asset restore is additive and overwriting, not mirroring

For each selected asset directory, importAssetDir() walks the extracted source and copies every file to the target with REPLACE_EXISTING.

The resulting behavior is:

a missing destination file is added;
a same-path destination file is overwritten;
a destination file absent from the archive is retained.

The third rule is easy to miss. The importer does not delete the target directory and does not synchronize it to an exact snapshot. This reduces destructive surprises, especially when a user imports only one collection. It also means migration may leave obsolete skills, commands, memories, or skin files in place.

The distinction between “restore a portable selection” and “replace the complete local state” is a general design choice worth making explicit. The former is safer for ordinary users. The latter would require a much stronger review and deletion model.

The asset operation is also not backed by an asset-level pre-import snapshot. If a file is overwritten and a later operation fails, the profile service does not automatically restore the old asset.

Commit is not transactional

The commit sequence is ordered: unpack and validate, apply settings if selected, then process skills, agents, commands, memory, and skins. There is no transaction spanning these filesystem operations, no staging tree swapped into place as one unit, and no compensating rollback.

Suppose settings has already been written and several skill files have been copied when an agents file fails. The previous changes remain. The settings backup may allow manual restoration of the old settings file, but it does not restore overwritten assets and does not reverse the whole operation.

This is not necessarily a defect for a compact local utility. Transactional filesystem migration is complex, especially when multiple directories and user-created files are involved. It is, however, a boundary that must appear in runbooks. Treat commit as a sequence of applied writes, not as an all-or-nothing change.

A cautious migration procedure is therefore straightforward:

Make an independent backup of the relevant SolonCode home data.
Inspect the archive source and contents before uploading it.
Preview the exact keys that will be submitted.
Prefer a separate credential provisioning step.
Commit in a controlled environment, possibly in smaller selections.
Verify settings and representative files after commit.
Reload or restart according to the changed configuration.

Reload is not the same as restart

The profile commit itself does not call reload. The controller's response and comments point callers to /web/settings/reload afterward.

WebSettingsController.settingsReload() invokes AgentSettings.reloadInPlace(). The settings class first loads and parses a disk snapshot, fills runtime defaults, compares content, and only then copies values into the current instance. The tests for AgentSettingsReloadTest.java cover useful in-place properties such as retaining final group object identity, replacing maps in place, preserving memory on corrupt input, and layering local settings over global settings.

The reload controller applies or diffs several categories, including general settings, permissions, default model, models, MCP servers, and API servers. But the implementation explicitly warns about two categories:

mountPools changed; memory updated, restart recommended for full runtime effect
lspServers changed; memory updated, restart recommended for full runtime effect

In other words, mountPools and lspServers may be updated in memory while their complete runtime effect still requires a restart. Also, reload with apply=false refreshes memory without applying engine-side changes.

A migration runbook should not say “import, and everything is hot.” It should say “import, reload where appropriate, and restart when the runtime warning requires it.”

What the current tests prove—and do not prove

ProfileServiceTest.java contains 12 tests. They were also run against the reviewed source commit with:

mvn -pl soloncode-cli -am \
  -Dtest=ProfileServiceTest \
  -Dsurefire.failIfNoSpecifiedTests=false \
  test

The run completed with 12 tests, zero failures, zero errors, zero skipped, and Maven BUILD SUCCESS. Reading the assertions shows a focused baseline:

selected-key export is checked;
default masking and explicit plaintext export are checked for apiKey;
basic manifest structure and schema version are checked;
empty selection is rejected;
missing manifests and invalid schema cases are rejected;
commit independently validates schema;
an existing masked apiKey is preserved during settings import;
a deleted skill file can be restored;
one ../ Zip Slip entry is skipped.

This is useful coverage of the central happy paths. It is not complete coverage of the six-key feature or the security boundary.

The tests do not directly cover the controller's 64 MiB upload limit. They do not exercise the 256 MiB cumulative extraction boundary. They do not verify temporary directory cleanup. They do not verify same-name asset overwrite together with retention of extra destination files. They only incidentally execute settings backup logic without asserting the backup file's existence, content, or warning.

They also do not construct a partial failure to demonstrate the non-transactional result. They do not test preview A followed by commit B. Only apiKey is tested among the six exact secret names. There is no asset file containing a secret to demonstrate that assets are copied without scanning. Agents, commands, memory, and skins lack the same file-level positive restore coverage given to skills.

The test suite also cannot cover controls that the implementation does not have: entry-count limits, compression-ratio limits, per-file extraction limits, encryption, signatures, or cryptographic hashes.

The right conclusion is neither “the feature is untested” nor “the feature is fully secure.” The source and tests together show a sensible baseline with clearly identifiable follow-up work.

The engineering lesson

SolonCode's Profile backup design is valuable precisely because its guarantees are bounded. It defines a portable schema v1 ZIP. It distinguishes settings from five asset directories. It filters settings by known top-level groups. It masks six exact string field names by default. It makes plaintext export explicit. It limits compressed uploads to 64 MiB and cumulative extraction to 256 MiB. It performs basic Zip Slip path checks and attempts temporary-directory cleanup. It restores assets by adding and replacing files without deleting extra destination files.

It does not encrypt archives. It does not authenticate their source. It does not hash or sign their contents. It does not scan directory assets for secrets. It does not bind preview bytes to commit bytes. It does not provide entry-count, compression-ratio, or per-file limits. It does not make restore transactional or automatically roll back. It may require a restart for the complete runtime effect of mountPools or lspServers changes.

That is a credible migration utility boundary, not a secret manager boundary. The practical design principle is simple: make the portable unit explicit, make destructive behavior limited, and document every guarantee narrowly enough that operators can build the missing controls around it.

For any tool that moves AI configuration, this is the standard worth aiming for. Security is not the number of safeguards listed in a settings page. It is the precision of the contract between what the code protects, what it leaves untouched, and what the person operating the migration must still verify.

Source paths

The implementation and tests discussed here are in the SolonCode repository:

soloncode-cli/src/main/java/org/noear/solon/codecli/portal/web/service/ProfileService.java
soloncode-cli/src/main/java/org/noear/solon/codecli/portal/web/settings/ProfileSettingsController.java
soloncode-cli/src/main/java/org/noear/solon/codecli/portal/web/WebSettingsController.java
soloncode-cli/src/main/java/org/noear/solon/codecli/config/AgentSettings.java
soloncode-cli/src/test/java/org/noear/solon/codecli/portal/web/service/ProfileServiceTest.java
soloncode-cli/src/test/java/org/noear/solon/codecli/config/AgentSettingsReloadTest.java

The source claims in this article were checked against repository commit 334284123ca6c7069cc58f24e044f8785bd6dc9d. The focused ProfileServiceTest run passed as described above; no performance measurement is being claimed.

File Events Are Hints: Keeping SolonCode's Workspace Tree in Sync

Solon Framework — Sat, 05 Sep 2026 11:04:19 +0000

A file tree looks like a read-only view of a directory. In a coding agent, it is closer to a live distributed projection.

The filesystem changes outside the browser. A Java watcher observes platform events. A WebSocket transports them. JavaScript updates a partially expanded DOM. Meanwhile, the user can collapse a directory, reconnect the page, switch workspaces, or ask the agent to create a whole package tree in one turn.

That means a file event is useful, but it is not the file tree itself. It is a hint that helps the UI move toward the current filesystem state.

SolonCode's public source provides a compact case study in that distinction. Its workspace tree combines recursive watching, change coalescing, incremental DOM patches, lazy reconciliation, and reconnect-time refresh. The interesting part is not any single function. It is the boundary between the event stream and the authoritative directory scan.

The real SolonCode Web file panel, captured from a clean demo workspace. The screenshot is cropped to the file panel and contains no model, endpoint, account, session, or local absolute path.

This article follows the public repository at commit 58c19665. That snapshot is later than the latest formal release verified while writing, v2026.8.30, so treat this as a source analysis rather than a guarantee about every installed binary.

The synchronization pipeline

At a high level, the path is:

filesystem
  -> JDK WatchService
  -> ChangeEntry(wsId, path, kind, type)
  -> net-effect merge by workspace + path
  -> system.filer_change over WebGate
  -> onFilerChange(payload)
  -> incremental DOM update or lazy reconciliation

The backend and frontend have different responsibilities.

The backend knows which physical root changed and converts platform events into a small transport contract. The frontend knows which parts of the tree are currently rendered, expanded, collapsed, or absent. Neither side alone owns the complete user-visible state.

That division is important. Sending the whole tree after every save would be simple but expensive and disruptive. Sending only raw events would be cheap but would force the browser to pretend that it has a complete, perfectly ordered log. SolonCode takes a hybrid approach.

One watcher, multiple roots

A SolonCode workspace can expose more than its launch directory. It can also include enabled mounts. In WorkspaceManager.doCreateWorkspaceContext(), each workspace context creates its own FileWatchService, registers the launch workspace as the workspace root, and then registers enabled mounts.

The root ID travels with every change:

public static class ChangeEntry {
    public final String wsId;
    public final String path;
    public final String kind;
    public final String type;
}

This prevents a path such as src/App.java in one mount from being confused with the same relative path in another.

The mount type also determines the downstream action:

a FILES mount broadcasts file changes to the Web UI;
a SKILLS mount refreshes the corresponding Skill group;
an AGENTS mount refreshes the matching agent definition.

So the watcher is shared infrastructure, but its handlers preserve domain boundaries. Not every filesystem event is a file-tree event.

Recursive registration is part of correctness

JDK WatchService registers directories, not an abstract recursive tree. SolonCode's registerTree() walks the existing directory hierarchy and registers each relevant directory for create, delete, and modify events.

The second half is easy to miss: when pollEvents() observes a newly created directory, it calls registerTree() for that new subtree. Without that step, the UI might show the new directory but never hear about files created inside it later.

The watcher also excludes noisy or irrelevant directories such as:

.git
node_modules
target
build
.gradle
.mvn

This is not merely a performance tweak. A dependency installation or build can produce thousands of events that do not belong in the coding agent's navigational tree. Filtering them at the watcher boundary reduces transport noise and avoids unnecessary DOM work.

The public test suite covers both sides of this behavior: changes inside a newly created nested directory are detected, while changes under an excluded .git directory are not dispatched.

Coalesce operations into a net effect

A single human action rarely maps to one low-level filesystem event. Saving a file may create, modify, replace, or delete temporary paths. Generators can emit bursts. Editors may use an atomic-write pattern.

SolonCode does not put every observation directly onto the WebSocket. Pending changes are keyed by workspace ID + relative path, and mergeChange() reduces repeated operations to a structural net effect.

The verified rules include:

create + modify -> create
create + delete -> no event
delete + create -> create
modify + delete -> delete

This small state machine matters more than a generic "debounce" label.

Imagine that src/NewFile.java is created and immediately modified before the current batch is delivered. The tree only needs to learn that a file now exists. It does not need two DOM operations. If a temporary file is created and deleted within the same pending window, the correct structural outcome is no node at all.

The implementation uses concurrent compare-and-replace operations in putChange(), so updates to the same key are merged without turning the entire pending map into one coarse lock.

After collection, flushChanges() groups entries by wsId and dispatches each root's list only to that root's handlers. A failing handler is caught so it does not prevent another handler from receiving its batch.

The event envelope is intentionally small

The browser receives a SAEP-style event named system.filer_change. Its useful shape is:

{
  "event": "system.filer_change",
  "timestamp": 1716153600000,
  "payload": {
    "changes": [
      {
        "wsId": "workspace",
        "path": "src/Foo.java",
        "kind": "create",
        "type": "file"
      }
    ],
    "createdAt": 1716153600000
  }
}

The event carries identity and intent, not file content and not a serialized tree.

That keeps the hot path small. It also makes the contract honest: the browser is told that a path was observed as created, deleted, or modified. It is not told that the message is an immutable transaction record or a complete filesystem snapshot.

app-streaming.js treats this as a system-level event without a chat session ID and routes the payload to onFilerChange().

Apply structural changes in dependency order

The frontend sorts each batch before touching the DOM:

delete;
modify;
create.

Depth breaks ties:

deletes run deepest path first;
creates run shallowest path first.

That is a simple dependency rule. If a directory subtree disappears, removing children before parents avoids trying to operate through a parent that is already gone. If a new subtree appears, creating parents before descendants gives later operations somewhere to attach.

It also helps rename-like sequences. WatchService does not give the browser a domain-level rename command here; the visible effect can arrive as delete plus create. Processing deletions first reduces path conflicts in the same batch.

The ordering is not a claim that every operating system emits identical events. It is a defensive frontend rule for the events that do arrive.

Patch visible nodes; mark invisible branches dirty

applyFilerChange() separates content changes from structural changes.

delete calls removeTreeNode();
create calls ensureTreeNode();
modify normally does nothing to the structure;
a modify event can still create a missing file node for compatibility with older or incomplete event shapes.

The key optimization appears when the parent directory is collapsed.

A collapsed branch does not need an immediate full child list. In fact, the browser may not have rendered those children at all. Instead of fetching and painting invisible nodes, SolonCode marks the parent with data-dirty="1".

When the user expands that directory later, the click handler sees the dirty marker, requests the real one-level directory listing, and replaces that branch from the authoritative scan.

This creates two update modes:

visible expanded branch -> patch now
collapsed/unrendered branch -> mark dirty, reconcile on expansion

That is a useful general pattern for large lazy trees. Event processing stays proportional to what the user can currently see, while a later read repairs uncertainty.

Insert without redrawing siblings

When the parent container is visible, insertNodeSorted() builds one new node and places it among existing siblings.

The ordering matches the backend tree service:

directories before files;
names compared case-insensitively within each group.

The function also checks for an existing node before insertion. That makes repeated or compatibility events harmless at the DOM level and, more importantly, leaves existing nodes untouched.

Leaving siblings untouched preserves their bound handlers and current UI state. A full innerHTML replacement might produce the same names but still collapse directories, reset focus, lose hover state, or move the scroll position.

This concern is visible in the project's history. The v2026.7.13 notes explicitly describe replacing refresh-driven behavior with dynamic deletion and addition because expanded file-tree nodes could collapse after a refresh. The implementation commit 14e6510 changes the Java watcher, the frontend tree code, and the watcher tests together.

Reconciliation still needs an authoritative read

Incremental events are the fast path, not the only path.

When the WebSocket reconnects, connectWebGate().onopen calls loadTree(). If a tree already exists, the call enters smartRefreshRoot() instead of treating the panel as an empty first load.

The refresh process:

records expanded workspaces and directory paths;
reloads the workspace-root list;
rebuilds the visible roots;
restores expanded workspaces;
sorts saved paths by depth;
reloads expanded directories serially, parent before child.

The directory requests are authoritative reads through the file-tree HTTP endpoint. This repairs the projection after a connection gap without pretending that the browser received every missed event.

Serial restoration is deliberate. A child node cannot be found until its parent directory has been loaded into the DOM. Depth sorting establishes the dependency order, and serial requests make that order explicit.

This is the larger design lesson:

Events provide low-latency hints. Reads provide truth.

A robust live tree usually needs both.

What the current public source does not claim

It is useful to separate implemented mechanisms from possible hardening work.

In the public source snapshot analyzed here, smartRefreshRoot() clears the live tree and then rebuilds it. The code does preserve expanded paths, but it does not implement a complete detached-tree build followed by one atomic swap.

The same snapshot does not show:

a refresh generation token that rejects stale async results;
a structural fingerprint that skips an unchanged DOM commit;
explicit scrollTop and scrollLeft restoration;
a whole-refresh watchdog;
per-request timeout handling inside the file-tree module;
a frontend JavaScript test suite for refresh races.

Those are not hidden claims or implied features. They are useful review questions for the next reliability pass.

For example, once a refresh spans several requests, an older request can finish after a newer refresh has begun. A generation token can prevent stale work from committing. Building into a detached container can keep the old tree visible until the replacement is complete. A structural fingerprint can make a no-change refresh a zero-DOM-change operation. A watchdog can prevent a hung request chain from leaving a permanent in-flight state.

The correct article about a real codebase should say where the implementation stops, not quietly turn a design wish list into product documentation.

Test the semantics, not just the watcher callback

The current Java tests provide a solid backend baseline. They cover:

file create, modify, and delete;
changes in an existing subdirectory;
automatic registration of a newly created directory;
exclusion of .git changes;
isolation between multiple roots;
multiple handlers on one root;
the system.filer_change JSON shape;
net-effect merge rules;
ChangeEntry equality.

A fuller end-to-end matrix would add browser-level assertions:

a create event inserts one correctly sorted node;
a delete removes the deepest visible node first;
a collapsed parent becomes dirty but is not eagerly rendered;
expanding a dirty parent replaces it from an HTTP listing;
reconnect refresh preserves the expanded path set;
events arriving during refresh do not disappear;
an unchanged refresh does not disturb scroll or selection;
a failed directory request leaves a recoverable UI.

The distinction matters because a watcher test can prove that Java observed a path while the browser still displays the wrong tree. Synchronization correctness crosses process and UI boundaries.

A reusable design checklist

For any live workspace tree, ask these questions:

Observation

Are existing directories registered recursively?
Are newly created directories registered too?
Which generated or hidden directories are excluded?
How are multiple workspace roots distinguished?

Reduction

Are repeated changes merged by stable identity?
What is the net effect of create/modify/delete sequences?
Are temporary create-delete pairs eliminated?

Transport

Does the event carry root, relative path, kind, and node type?
Is the event a hint or a promised transaction log?
What happens during disconnection?

Projection

Are deletes and creates applied in dependency order?
Can visible nodes be patched without replacing siblings?
Are collapsed branches marked dirty and lazily reconciled?

Recovery

Is there an authoritative directory-read path?
Does reconnect trigger reconciliation?
Are expanded paths restored parent-first?
Can stale async work overwrite a newer result?
Can a failed or hung refresh recover?

Verification

Do tests cover event reduction as well as event capture?
Do browser tests assert DOM stability, not only final node names?
Are scroll, focus, selection, and expanded state part of the contract?

The tree is a projection, not a ledger

The most useful shift is conceptual.

A filesystem watcher is not the source of truth. A WebSocket is not the source of truth. The DOM is certainly not the source of truth. They are stages in a projection whose authority remains the workspace on disk.

SolonCode's design reflects that reality in practical layers:

recursively observe relevant roots;
merge noisy low-level events into structural outcomes;
patch the visible tree incrementally;
defer work for collapsed branches;
reconcile from directory scans after reconnect;
preserve expansion dependencies while rebuilding.

Once file events are treated as hints rather than facts, the architecture becomes easier to reason about. The fast path can stay fast, and the recovery path can remain honest.

SolonCode in CI: Headless Runs, JSONL Events, and Remote Workspace Execution

Solon Framework — Fri, 04 Sep 2026 21:22:57 +0000

Interactive coding agents are designed for a person at a keyboard. CI is not. A pipeline needs a process it can start, observe, constrain, and classify without waiting for a human to approve the next tool call.

SolonCode has a separate run entry point for that boundary. It is a one-shot, non-interactive execution mode: give it a prompt, let the agent work to a terminal result, consume text or structured output, and use the exit code to decide what the pipeline should do next.

The useful mental model is not “a smaller chat UI.” It is “an agent process with a machine-readable contract.”

The smallest useful CI invocation

soloncode run "Review the changes in this pull request. Focus on security and correctness." \\
  --output-format json \\
  --allowedTools "Read,Grep,Glob,Bash(git log *),Bash(git diff *)" \\
  --disallowedTools "Bash(rm *)" \\
  --permission-mode dontAsk \\
  --max-turns 15 \\
  --max-budget-usd 2.0 > review.json

This command makes several choices explicit:

run does not start the interactive UI.
json produces one result object for a script to parse.
The tool allowlist describes what the reviewer may inspect.
The command rule blocks destructive rm calls while allowing selected Git reads.
dontAsk is appropriate for an unattended job: an operation requiring approval is not turned into a hidden prompt.
max-turns provides a runtime bound.
max-budget-usd gives the result a cost threshold.

A CI wrapper should check the process status before trusting the output:

set +e
soloncode run "Review the changes in this PR" \\
  --output-format json \\
  --allowedTools "Read,Grep,Glob,Bash(git diff *)" \\
  --permission-mode dontAsk \\
  --max-turns 15 \\
  --max-budget-usd 2.0 > review.json
status=$?
set -e

jq -r '.error // .result' review.json

case "$status" in
  0) echo "review completed" ;;
  2) echo "agent reached the maximum number of turns" >&2; exit 1 ;;
  4) echo "agent exceeded the configured budget" >&2; exit 1 ;;
  *) echo "agent execution failed" >&2; exit 1 ;;
esac

The distinction between the exit code and the JSON body matters. A result can be valid JSON and still represent an incomplete or over-budget execution.

Three output modes, three consumers

soloncode run supports three output formats.

`text`: a human-oriented result

The default writes the final answer as plain text. It is useful when a shell script only needs to display a report or append it to a log, but it is not a stable envelope for downstream automation.

`json`: one terminal object

JSON is the natural choice for a job that waits for completion. The object can contain the result, error state, session ID, metrics, estimated cost, and—when a schema is supplied—structured_output.

soloncode run "List public API methods in src" \\
  --output-format json \\
  --allowedTools "Read,Grep,Glob" \\
  --permission-mode dontAsk \\
  --json-schema '{"type":"object","properties":{"methods":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"file":{"type":"string"}}}}}}' \\
  | jq '.structured_output.methods'

The schema is an output constraint, not a permission policy. Keep the two concerns separate: json-schema describes what the answer should look like; tool and permission options describe what the agent may do while producing it.

`stream-json`: an observable event stream

For longer tasks, waiting silently for one final object is a poor operational experience. With stream-json --verbose, SolonCode emits one JSON object per line. The event stream includes initialization, assistant text, tool calls, tool results, and a terminal result or error.

soloncode run "Inspect the build and explain the first failing test" \\
  --output-format stream-json --verbose \\
  | tee run.jsonl \\
  | jq -r 'select(.type=="result") | .result'

Because each event is a line, a pipeline can retain the complete trace and independently project the part it needs:

# Observe tool calls without parsing the final prose
jq 'select(.type=="assistant")
    | .message.content[]?
    | select(.type=="tool_use")
    | {name, input}' run.jsonl

Without --verbose, stream-json emits only the final result event. That behavior is useful when the caller wants the stream-shaped terminal record but does not need intermediate activity.

Prompt input: argv or stdin

A prompt can be the positional argument or come from a redirected stdin stream. If both are present, the command-line prompt wins.

cat build-error.log | soloncode run \\
  --output-format json \\
  "Analyze this build failure and identify its root cause"

This is more than a convenience. Keeping large or generated input out of shell interpolation avoids quoting surprises and makes it possible for a CI step to pass a report directly into the agent.

run is deliberately one-shot. It does not accept the persistent JSONL input mode. If a process must remain alive and receive multiple user messages from stdin, the separate soloncode stream entry point is the clearer lifecycle contract.

Tool restrictions are part of the job definition

A prompt saying “do not change files” is not an enforcement mechanism. In unattended execution, restrictions should be represented by options.

For a read-only review:

soloncode run "Review this repository" \\
  --allowedTools "Read,Grep,Glob" \\
  --permission-mode dontAsk

For a plan-only task:

soloncode run "Propose a migration plan for the authentication module" \\
  --permission-mode plan

For a narrowly scoped automatic edit, acceptEdits allows file-oriented tools while other operations remain rejected by the permission rules. It should still be combined with a specific allowlist and a turn limit.

The ToolName(pattern) form is useful when a whole tool is too broad:

--allowedTools "Read,Grep,Bash(git diff *),Bash(git log *)"
--disallowedTools "Bash(rm *)"

The pattern is matched as a tool command rule. This is preferable to allowing arbitrary shell execution merely because the task needs git diff.

Bound the agent in three dimensions

A robust CI invocation usually has three independent bounds:

Capability bound — which tools and commands can be called.
Work bound — how many reasoning/action turns may run.
Cost bound — how much estimated usage the result may report.

--max-turns is the runtime guard. --max-budget-usd is currently checked after execution completes, so it should not be treated as a hard mid-run kill switch. Use both, and make the pipeline’s policy explicit for exit code 4.

--fallback-model can make a scheduled job more tolerant of primary-model unavailability, but it does not remove the need for bounded work and a clear output contract:

soloncode run "Run the nightly code-health inspection" \\
  --output-format json \\
  --allowedTools "Read,Grep,Glob,Bash(git log *)" \\
  --permission-mode dontAsk \\
  --max-turns 25 \\
  --max-budget-usd 3.0 \\
  --fallback-model haiku \\
  > reports/health.json

Two phases with a resumable session

Some jobs are easier to reason about when analysis and modification are separate phases. The JSON result exposes a session ID that can be used by a later invocation:

set -euo pipefail

soloncode run "Analyze src/auth and list the risks" \\
  --output-format json --max-turns 10 > phase1.json

session=$(jq -r '.session_id' phase1.json)

soloncode run "Using that analysis, write unit tests for src/auth" \\
  --resume "$session" \\
  --output-format json \\
  --permission-mode acceptEdits \\
  --max-turns 20 > phase2.json

The session is an agent conversation boundary, not a replacement for Git branches, worktrees, or artifact storage. If the second phase edits files, the CI job still needs its normal diff and test checks.

Remote execution: the same contract behind HTTP

A local shell is not always the right integration point. A build service may already run SolonCode on a worker, or a Java application may want to submit work without installing the CLI.

The /web/run endpoint carries the same one-shot execution contract over HTTP:

{
  "prompt": "Analyze this module",
  "options": {
    "output_format": "stream-json",
    "max_turns": 15,
    "allowed_tools": ["Read", "Grep", "Bash(git diff *)"],
    "permission_mode": "dontAsk"
  },
  "workspace": "my-project",
  "metadata": {"request_id": "ci-001"}
}

The HTTP representation uses snake_case, while the CLI keeps its flag spelling. Unknown option fields are rejected instead of silently ignored. That failure mode is important: a typo must not make a caller believe that a safety option was applied.

For streaming requests, the response is SSE. Each data: line contains the same JSON event that the CLI would write as one JSONL line, so an existing event parser can be reused:

curl -N -X POST http://127.0.0.1:18080/web/run \\
  -H "Authorization: Bearer $TOKEN" \\
  -H "Content-Type: application/json" \\
  -H "Accept: text/event-stream" \\
  -d '{"prompt":"Analyze code quality","options":{"output_format":"stream-json"}}' \\
  | grep '^data:' \\
  | sed 's/^data: *//' \\
  | jq -r 'select(.type=="result") | .result'

The server implementation starts a child App run process in the selected workspace. That choice preserves the CLI’s argument parsing and execution semantics while keeping per-request engine options from mutating the web process’s interactive engine. It also means a request pays a JVM startup cost; the isolation and zero-drift properties are the more important trade-off for this boundary.

The endpoint adds network-specific semantics:

Bearer authentication is required.
The server accepts registered workspace identifiers, not arbitrary paths.
bypassPermissions is rejected for /web/run.
A session already running receives a conflict response rather than interleaving messages.
/web/run/interrupt returns 202 and destroys the active child process.
A client disconnect is treated as a reason to stop work, not as permission to keep an orphaned agent running.

Do not expose this endpoint as an unauthenticated general-purpose shell. It drives an agent with file and command capabilities. Loopback binding, token authentication, workspace restrictions, permission-mode narrowing, and audit logging are security requirements, not optional deployment polish.

Exit codes are an API

The local and remote forms intentionally distinguish execution conclusions from transport failures.

Exit code	Meaning
0	Completed successfully
1	Agent or API runtime error
2	Maximum turn limit reached
3	No prompt was supplied
4	Estimated cost exceeded the configured budget

For /web/run, success is HTTP 200. A runtime error maps to HTTP 500, and a missing prompt to HTTP 400. Reaching the turn or budget limit remains HTTP 200 with an error state in the result, because the request was accepted and executed; the client should inspect the payload rather than blindly retrying at the HTTP layer.

That distinction prevents a common automation bug: retrying an expensive, already-completed-but-incomplete agent run as if the network had failed.

A practical adoption sequence

Start small:

Run a read-only task locally with json output.
Add max-turns and an explicit tool allowlist.
Make the CI step archive the JSON result and check the exit code.
Add a schema when another program needs fields, not prose.
Use stream-json when operators need progress or an audit trace.
Split analysis and edits with --resume only after the single-phase job is reliable.
Move to /web/run when execution must live on a service worker, and retain the same parser and policy checks.

The central design decision is to treat the agent invocation as a typed, bounded job. Prompts provide intent; options define capability and limits; events provide observability; exit codes provide control flow. That is what makes SolonCode useful in CI rather than merely runnable from a CI shell.

From DOM Snapshots to Visual Regression: Building a Web Workflow with SolonCode's agent-browser Skill

Solon Framework — Wed, 02 Sep 2026 13:14:41 +0000

Browser automation becomes useful to a coding agent when it is more than a bag of clicks.

A reliable workflow needs a way to discover the current page, act on the right element, verify the result, and leave evidence behind. It also needs to survive navigation, login state, dynamic DOM changes, and the uncomfortable fact that browser actions can have real side effects.

SolonCode ships an agent-browser skill that packages that workflow as a reusable skill asset. The interesting part is not that it can click a button. It is the discipline around the click:

navigate to a page;
take an accessibility snapshot;
interact using references from that snapshot;
take a fresh snapshot after the page changes;
compare the before and after states;
capture a screenshot or recording when visual evidence matters.

This article follows the skill as it exists in the SolonCode source tree. It focuses on what the asset actually documents, including its security boundaries and limitations.

The snapshot is the synchronization point

The skill's core loop is deliberately small:

open
  -> snapshot -i
  -> click / fill / select
  -> snapshot again

agent-browser snapshot -i returns interactive elements with references such as @e1. A later command can use that reference to fill a field or click a button.

The important rule is that references belong to a page state. After navigation or a DOM-changing action, the workflow takes a new snapshot instead of assuming that the old @e1 still means the same thing.

That makes the snapshot a synchronization point between the browser and the agent. The agent does not operate on a stale mental picture of the page; it re-reads the page before continuing.

A minimal form workflow looks like this:

agent-browser open https://example.com/signup
agent-browser wait --load networkidle
agent-browser snapshot -i

# Use the references returned by the snapshot.
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "jane@example.com"
agent-browser click @e3

agent-browser wait --load networkidle
agent-browser snapshot -i

The references in this example are illustrative. They must come from the current snapshot; they are not stable selectors to hard-code across pages.

Accessibility snapshots are more than a locator trick

A snapshot gives the agent a compact representation of the page's interactive surface. It can expose buttons, textboxes, links, checkboxes, and other controls without requiring the workflow author to invent CSS selectors for every page.

When a page changes, the agent can compare the new tree with the previous one:

agent-browser snapshot -i
agent-browser click @e2
agent-browser diff snapshot

The diff reports additions and removals in a form similar to a text diff. This is useful for a test workflow because “the click completed” is not the same as “the expected state appeared.” A menu opening, a validation message appearing, or a result row changing can become an explicit assertion in the workflow.

For machine-readable consumers, the skill also documents JSON output:

agent-browser snapshot -i --json
agent-browser get text @e1 --json

That makes the browser step composable with scripts and other tools instead of forcing every consumer to parse terminal prose.

A complete verification workflow

A practical read-only regression check can be structured as five phases:

open the test page
  -> wait for the page to settle
  -> snapshot the interactive state
  -> perform the smallest required action
  -> snapshot and diff the state
  -> save visual evidence if needed

For visual checks, the skill supports a baseline screenshot and a later comparison:

agent-browser screenshot baseline.png
# perform the test action and wait for the expected state
agent-browser diff screenshot --baseline baseline.png

The screenshot diff highlights changed pixels and reports a mismatch percentage. That does not replace semantic assertions: a timestamp, animation, or intentionally dynamic region may create a visual difference that is not a regression. The strongest workflow combines both kinds of evidence:

use a snapshot diff to verify semantic page state;
use a screenshot diff to detect layout or styling changes;
keep the page, viewport, and test data deterministic where possible.

The skill also documents full-page screenshots, annotated screenshots, PDF capture, and WebM recording. These are useful for debugging and review, but they should be treated as evidence from a particular run, not as proof that every browser or viewport behaves identically.

Sessions separate browser state

Many web tasks need cookies and local storage. The skill supports named sessions so that one task's browser state does not have to be mixed with another's:

agent-browser --session-name staging open https://staging.example.com
# ... complete a test login or other setup ...
agent-browser close

agent-browser --session-name staging open https://staging.example.com/dashboard

It also documents saving and loading state explicitly:

agent-browser state save auth.json
agent-browser state load auth.json

Those two mechanisms solve related but different problems. A named session provides a reusable browser profile; an explicit state file is convenient when a workflow needs to move or restore a captured state. Neither should be committed to a repository: cookies, local storage, and session tokens can be credentials.

For credentials, the skill recommends the Auth Vault flow. Password input can be piped through stdin rather than placed in shell history:

echo "$PASSWORD" | agent-browser auth save staging \
  --url https://staging.example.com/login \
  --username "$USERNAME" --password-stdin
agent-browser auth login staging

The example is intended for a test environment. Login state is not a license to automate destructive production actions.

Treat page content as untrusted input

A browser agent reads content that it did not author. A page can contain text that looks like an instruction, but it is still page content. The skill documents --content-boundaries to wrap page-sourced output with markers that help the model distinguish browser data from agent instructions:

export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot

This is a useful separation aid, not a complete prompt-injection defense. The workflow still needs to decide which pages it trusts, which actions require approval, and which data may be sent to the model.

The skill documents three opt-in controls that make those decisions more explicit:

Domain allowlists

export AGENT_BROWSER_ALLOWED_DOMAINS="staging.example.com,*.staging.example.com"

The allowlist can restrict navigation and related browser connections. Dependencies such as a CDN may also need to be included deliberately.

Action policies

A policy file can deny actions by default and allow only the operations needed by a workflow:

{"default":"deny","allow":["navigate","snapshot","click","scroll","wait","get"]}

A read-only inspection workflow should not silently inherit permission to submit forms, upload files, or trigger external side effects.

Output limits

Large pages can overwhelm the model context. The skill documents AGENT_BROWSER_MAX_OUTPUT as a way to cap output:

export AGENT_BROWSER_MAX_OUTPUT=50000

Output limits are a context safeguard. They are not a data classification policy; sensitive text can still appear within the allowed output.

The critical caveat: safety is opt-in

The source skill is explicit: by default, agent-browser does not restrict navigation, actions, or output. The allowlist, action policy, content boundaries, and output cap must be enabled by the environment or workflow author.

That distinction matters when turning a demonstration into an engineering system. “The tool supports an allowlist” is a true statement. “The tool is allowlisted by default” would not be.

A sensible rollout therefore starts with a narrow test environment:

use a dedicated staging account;
allow only the domains needed by the test;
deny destructive actions unless the test explicitly needs them;
keep output bounded;
save screenshots and snapshots without saving credentials;
review any workflow that can submit, purchase, delete, publish, or send messages.

A skill asset, not just a command list

The value of this SolonCode skill is its layered structure. SKILL.md defines the operating contract and the core loop. Reference files provide deeper material for authentication, session management, proxy support, snapshot references, video recording, and profiling.

That separation makes the workflow easier to review. A maintainer can inspect the short trigger and operating rules first, then audit the detailed reference that a particular task needs. It also reduces the temptation to put every browser edge case into the model's initial context.

The reusable unit is therefore not “a model knows how to click.” It is:

workflow contract
  + browser commands
  + state and authentication guidance
  + verification steps
  + explicit safety configuration
  + evidence capture

This is the same reason a good test helper is more valuable than a raw HTTP client: it encodes the decisions that make repeated execution dependable.

What this skill does not promise

The source-backed boundaries are as important as the feature list:

snapshot references are page-state references, not permanent IDs;
content boundaries help distinguish page output but do not make page content trustworthy;
visual diffs need deterministic test conditions and still require interpretation;
saved browser state may contain secrets;
iOS automation has additional macOS, Xcode, Appium, and driver requirements;
browser automation can perform real-world side effects;
security controls are opt-in rather than automatic.

A workflow that states these limits is more useful than one that presents browser automation as a magical, risk-free operator.

Closing the loop

A robust browser workflow has a shape familiar to software engineers:

observe -> mutate -> observe -> compare -> record

SolonCode's agent-browser skill turns that shape into a reusable asset. Accessibility snapshots keep actions aligned with the current DOM. Sessions preserve deliberate state. Snapshot and screenshot diffs turn “it seemed to work” into inspectable evidence. Optional domain, action, content, and output controls give teams a place to define their safety boundary.

The final lesson is simple: browser automation should be reviewed like code. The clicks are only the implementation. The real asset is the contract around what the workflow may visit, what it may change, how it verifies success, and what evidence it leaves behind.

From write/edit to automatic feedback: How SolonCode closes the LSP loop

Solon Framework — Wed, 02 Sep 2026 06:56:25 +0000

A coding agent can write syntactically plausible code and still leave a broken project behind.

The obvious answer is to give the agent an lsp tool and let the model ask for diagnostics whenever it wants. SolonCode tried that shape first. The implementation put navigation and diagnostics in one tool, but diagnostics were effectively never requested. That result is not surprising: after a write, “check whether this introduced errors” is not an optional curiosity. It is part of the write operation’s feedback loop.

SolonCode’s current design makes that distinction explicit:

write and edit trigger diagnostics automatically after a successful change.
read warms the language server asynchronously without delaying the read.
The lsp tool is reserved for optional navigation such as definition, references, hover, symbols, and call hierarchy.

The interesting engineering is not starting a language server. It is keeping the file, the language server, the model, and the Web UI consistent while all four observe different representations of the same change.

Diagnostics should follow a write, not a model decision

The implementation note in the repository describes the original failure plainly: ten capabilities—nine navigation operations plus diagnostics—were exposed through one tool, and diagnostics were “never called” in practice.

That led to a three-layer design:

write / edit / apply_patch
    -> sync the file
    -> wait for diagnostics
    -> append diagnostics to the tool output

read
    -> warm up the language server asynchronously
    -> do not wait and do not change the read result

lsp
    -> definition / references / hover / symbols / call hierarchy ...

This is a useful rule for agent design: feedback that is necessary to evaluate a mutation belongs on the mutation path. Exploratory information can remain an explicit tool.

The separation also keeps the tool schema smaller and the model’s decision burden clearer. The model does not need to remember a second call after every edit just to discover whether the edit compiled.

The asynchronous part: waiting for the right diagnosis

A file write and an LSP diagnosis do not happen at the same time. The client must synchronize the document, the server must parse it, and the server may publish one or more diagnostic notifications.

SolonCode’s implementation uses syncFile and waitForDiagnostics(uri, timeoutMs) to connect those events. The wait path tracks the write time and expected document version. A diagnostic notification with a mismatching version is treated as stale rather than as evidence about the latest edit. A 150 ms debounce gathers bursts of notifications, and the default wait budget is 2,000 ms.

That budget is deliberately finite. A language server may be cold-starting or indexing a large workspace. Blocking an agent forever is worse than returning the most recent known result and making the uncertainty visible.

The trade-off is documented in the repository: the first write for a language can exceed the two-second budget during process startup and initial parsing; later writes normally have a warm server. A wait setting can be adjusted with -Dlsp.diagnosticsWait, but increasing it also adds latency to every write.

The important property is not that every diagnosis arrives before the tool returns. It is that the agent does not silently confuse an old diagnosis with the current edit.

Keep the model’s feedback useful

Raw LSP output is a protocol payload, not good model context. SolonCode’s LspDiagnosticReporter narrows it before injection:

only ERROR severity is retained;
each file is limited to 20 displayed errors;
additional errors are summarized as ... and N more;
positions are rendered as 1-based line and column numbers;
the file is represented by a workspace-relative path where possible;
the model-facing block asks it to fix the errors.

The resulting shape is intentionally compact:

LSP errors detected in this file, please fix:
<diagnostics file="src/main/java/example/Service.java">
ERROR [18:13] incompatible types ... (javac)
</diagnostics>

This is not just presentation polish. Without severity filtering and a cap, a language server can flood the next model turn with warnings, hints, generated-file paths, and repeated secondary messages. Automatic feedback still needs a context budget.

One result, two consumers

The same diagnostic is useful to two different consumers:

the model needs concise text so it can repair the code;
the Web user needs structured data so the UI can display a reliable explanation.

SolonCode keeps those concerns separate. ToolPresentationFilter handles the TOOL_END event for write and edit. Before the filter replaces a write result with the written content for display, it extracts the diagnostic block into ToolEndPayload.lsp and removes the model-facing diagnostic prose from the user-facing result.

That ordering is a small but important correctness detail. If the filter copied args.content into result first, the diagnostics appended to the result could be lost before they were parsed.

ToolLspInfo then carries a structured contract:

private String file;
private int errorCount;
private boolean truncated;
private List<ToolLspDiagnostic> items;
private boolean pending;

Each item has a line, column, message, and optional source. The browser does not parse XML or prompt wording. It renders the contract it receives.

This makes prompt tuning safe: changing the model-facing sentence does not silently become a front-end protocol change.

Clean, pending, and uncovered are different states

A diagnostic panel often has an implicit and dangerous assumption:

no errors shown = no errors exist

That assumption is not valid for an asynchronous language server. SolonCode distinguishes three cases:

State	Meaning	UI implication
Clean	The file was checked and no errors were found	show `LSP ✓`
Pending	A check was requested, but no conclusion arrived within the wait budget	show neither success nor error badge
None	No language server covers the file, or LSP is disabled	do not claim the file was checked

WebStreamBuilder builds this state without starting a process. It checks the recent file-check state first; when there is no record, it asks the manager whether any client covers the path. A covered file with no conclusion becomes PENDING, not CLEAN.

The front end applies the same rule in applyLspBadge: errors get an LSP N badge and can expand the tool card; a confirmed clean result gets LSP ✓; a pending result gets no badge. That restraint matters. A blank badge is less satisfying than a green check, but it is more honest.

A real synchronization bug: jdtls received the change twice

The most instructive bug appeared only after Java diagnostics became observable. The disk file was correct, but jdtls reported a duplicate method, a stray closing brace, and line numbers beyond the file’s actual length.

The cause was a double application of one change. For an already-open document, the client sent both:

workspace/didChangeWatchedFiles(Changed), which caused jdtls to reread the file from disk; and
textDocument/didChange, whose replacement range had been calculated against the old text.

After the first event, the server already held the new text. Applying a range sized for the old text then left part of the new document behind. The server’s document became torn even though the disk file remained clean.

The fix had three parts:

once a document is open, use textDocument/didChange rather than also sending a watched-file event; watched-file notifications remain for files that are not open;
calculate a robust replacement end position using the later of the old and new text lengths;
lock synchronization by URI so reading, comparing, calculating, sending, and updating the tracked version are atomic.

The lesson generalizes beyond LSP: an integration can be logically correct at the file-system boundary and still be wrong at the protocol-state boundary.

Java adds a process-level constraint

SolonCode itself can run on older JDKs, while jdtls requires JDK 21 or newer. A child process normally inherits the parent process’s JAVA_HOME, so launching jdtls from a JDK 8 process can make it exit immediately.

The implementation addresses this without rewriting the user’s settings. JdkHomeUtil scans installed JDK directories and their release files, chooses a suitable JDK, and WorkspaceManager adds JAVA_HOME to the runtime copy of the built-in Java server configuration. An explicit user setting is respected, and the persisted configuration is left untouched.

That is a good example of keeping environment repair at the process boundary. The product can adapt the child process without committing a machine-specific absolute path into a project file.

What this architecture buys an agent user

The result is more than “SolonCode supports LSP.” It gives each operation a useful responsibility:

after a mutation, the agent receives actionable errors automatically;
before a mutation, reads can warm the server without making file browsing feel slow;
when the agent needs semantic exploration, navigation remains available explicitly;
in the Web UI, diagnostics are structured, bounded, and visible;
when the server is cold, unavailable, or unsupported, the UI avoids making a stronger claim than the evidence allows;
when the language-server integration fails, the successful write is not turned into a failed write.

That last property is especially important. The repository’s hook design treats language-server failures as auxiliary failures: diagnostic and warmup hooks swallow Throwable so an unavailable server cannot invalidate an otherwise successful file operation.

A coding agent should not merely produce code. It should receive the feedback needed to evaluate its own changes, while exposing uncertainty to the human who reviews the result.

SolonCode’s LSP work is therefore best understood as a feedback-loop design:

change -> synchronize -> wait (within a budget) -> filter ->
model repair + structured human-facing status

The hard part is not connecting to a server. The hard part is preserving truth across asynchronous state, noisy diagnostics, process-level runtime differences, and two different audiences. That is what turns LSP from a rarely used tool into part of the agent’s normal engineering loop.

Rewind or Fork? Two Ways to Recover a SolonCode Conversation

Solon Framework — Tue, 01 Sep 2026 18:41:39 +0000

A coding-agent conversation rarely fails all at once. More often, it drifts.

One incorrect assumption enters the context. The next answer builds on it. A correction adds more text but does not remove the original premise. Before long, the agent is consistently answering the wrong question.

At other times, nothing is wrong. You simply have two plausible approaches—a minimal patch and a structural refactor—and want to explore both without sacrificing the useful conversation that led you there.

Those situations look similar in a chat window, but they require opposite operations:

Rewind removes recent conversation history so you can redirect one timeline.
Fork preserves the original conversation and creates another timeline for a different experiment.

SolonCode supports both patterns. The important part is knowing which state you want to keep.

The shortest decision rule

Ask one question:

Is the recent context wrong, or is it valuable enough to preserve?

If it is wrong, rewind it. If it is valuable but you want another path, fork it.

Situation	Best action	What happens to the current route?
Recent messages pushed the agent in the wrong direction	Rewind	Recent conversation history is removed
The current route is valid, but you want to test an alternative	Fork	The original is preserved and a copy can diverge
The latest answer is wrong, but the request is still correct	Re-run	The last request is executed again
The current answer or task stopped before completion	Continue	The current work is extended

This is not merely UI vocabulary. Each action expresses a different intention about history.

Rewind: edit the conversation's recent past

SolonCode provides the built-in command:

/rewind [n]

It removes the most recent n messages from the current conversation context. The default is 1.

For example:

/rewind 3

means: discard the three most recent messages from this conversation, then continue from the earlier context that remains.

The unit matters: it is messages, not an assumed number of user/assistant pairs.

When rewind is useful

Imagine that you ask SolonCode to simplify an authentication module. During the conversation, you accept an assumption that the service is stateless. Two messages later, you discover that it must preserve server-side sessions for an existing client.

Adding another correction may not be enough. The old assumption remains in the conversation and can keep influencing later decisions.

A rewind lets you remove that contaminated tail and replace it with a clearer direction:

/rewind 3

Then:

Keep the existing server-side session contract. Limit the change to token parsing and add regression tests for the legacy client.

You are not asking the model to argue with its own recent history. You are removing that history from the active conversation context.

What rewind does not promise

Rewinding a conversation is not the same as rolling back a repository.

The command concerns conversation messages. Do not treat it as a replacement for:

git restore, git revert, or resetting a branch;
undoing a database migration;
reversing a command already executed in a terminal;
canceling a request already sent to an external service.

If an earlier agent run changed files, inspect the working tree and use normal version-control practices to decide what should be kept or reverted.

That distinction is essential for coding agents: conversation state and workspace state are related, but they are not the same transaction.

Fork: preserve the route and create another one

SolonCode Web added conversation fork/copy support in v2026.7.9.

Forking is appropriate when the existing conversation is useful. Instead of deleting its recent history, you copy the conversation and let the copy develop in another direction.

Consider a dependency upgrade that can be handled in two ways:

Route A: make the smallest compatible change;
Route B: refactor the integration around the new API.

The analysis collected so far—affected modules, tests, compatibility requirements, and constraints—is useful to both routes. Repeating that discovery from an empty chat would waste time and might produce a different baseline.

A fork gives both experiments a common conversational starting point. You can keep the original route intact while directing the copy toward the alternative.

Treat a fork as a conversation experiment

A useful fork has a hypothesis and the same acceptance criteria on both sides.

For example:

Original conversation

Implement the smallest compatible patch. Do not change public interfaces.

Forked conversation

Explore a structural refactor, but preserve behavior. Report every public API change before editing.

Then compare the outcomes using engineering evidence:

changed files and diff size;
test results;
public API impact;
migration risk;
maintainability;
unresolved assumptions.

The fork is valuable because the initial context is shared. The decision should still be based on the resulting code and tests, not on which conversation sounds more confident.

What fork does not imply

A copied conversation should not be confused with an isolated development environment.

The available product documentation supports the conversation-copy behavior. It does not, by itself, establish that each fork receives:

a separate Git worktree;
an isolated filesystem;
a separate container;
independent long-term memory;
automatic branch merging.

If two conversations operate on the same project directory, normal workspace coordination still matters. For genuinely parallel code experiments, create explicit Git branches or worktrees and assign each conversation a clear workspace.

Rewind versus fork: rewrite or preserve

The difference can be expressed as a timeline.

Before either operation:

A → B → C → D

If C and D are based on a bad assumption, rewind removes the unwanted tail:

A → B → C → D
        ↓ rewind
A → B → E

There is still one timeline. You changed where it goes.

If A → B → C → D is useful but you want to evaluate another option, fork preserves it:

A → B → C → D
        └→ E → F

Now there are two conversational routes. One is not automatically better; they are two experiments from a related baseline.

This leads to a reliable mental model:

Rewind is subtraction.
Fork is preservation plus divergence.

Where Re-run and Continue fit

Rewind and fork become easier to choose when placed beside two other SolonCode actions.

Re-run: keep the request, replace its result

Use Re-run when the latest user request is still correct but its answer is not. You want the agent to execute that request again rather than preserve the old result.

Typical intent:

Same request, another attempt.

Continue: keep the route, add more work

Use Continue when the current direction is correct but incomplete. The agent may have stopped halfway through a refactor, omitted tests, or ended before reporting verification results.

Typical intent:

Same route, keep going.

Rewind: remove misleading recent context

Use Rewind when the problem spans more than one answer or correction. The recent conversation itself has become a liability.

Typical intent:

Forget the recent messages; I want to redirect from an earlier context.

Fork: keep one route and test another

Use Fork when you do not want to destroy the current route. You need an alternative exploration with a comparable starting context.

Typical intent:

Preserve this route and let me try another one.

A practical recovery workflow

Suppose SolonCode is modernizing an order-processing module.

1. Interrupt before repairing history

If the agent is currently running and you can already see it moving in the wrong direction, stop or steer the active run first. Rewind is for conversation history that already exists; it is not the same operation as interrupting a live execution.

2. Inspect both states

Before choosing an action, inspect:

the last several conversation messages;
the Git diff or working-tree status;
commands and tests already run;
external side effects, if any.

This prevents the common mistake of repairing the chat while forgetting that the workspace has already changed.

3. Choose the smallest state operation

One bad answer, same request: Re-run.
Correct route, unfinished work: Continue.
Several misleading messages: Rewind.
Two valid approaches worth comparing: Fork.

4. Restate constraints after the operation

Do not continue with a vague “try again.” State the corrected constraint or the fork's hypothesis explicitly.

Good examples:

Preserve all public interfaces. Do not introduce a new cache. Run the existing integration tests before proposing additional changes.

In this alternative route, optimize for maintainability rather than minimum diff size. List migration risks separately.

5. Verify in the repository

Conversation controls help manage reasoning context; tests and version control validate the implementation.

At minimum, review:

git diff --stat
git diff

Then run the project's documented build and test commands. If you used a fork for A/B exploration, apply the same acceptance criteria to both routes.

A compact checklist

Before using Rewind:

Are recent messages actually harmful to later reasoning?
How many messages—not turns—should be removed?
Did earlier runs already modify files or external systems?
Have you captured any useful findings that would otherwise be lost?

Before using Fork:

Is the current conversation valuable enough to preserve?
What exact hypothesis will the copy test?
Will both routes use the same acceptance criteria?
Do code experiments need separate Git branches or worktrees?

The bigger lesson

Coding-agent productivity is not only about writing a better next prompt. It is also about controlling which history the next prompt inherits.

Use Rewind when recent history is part of the problem. Use Fork when recent history is an asset worth preserving. Use Re-run for another attempt at the same request, and Continue for more work on the same route.

Once those intentions are separated, conversation recovery stops being trial and error. It becomes a small, explicit state-management decision—and the repository remains the final source of truth.

Treat SKILL.md Like Code: Reviewable Workflows in SolonCode

Solon Framework — Mon, 31 Aug 2026 23:08:52 +0000

A prompt can be useful once. A Skill is different: it is an instruction package that will be discovered, selected, and reused by an agent later.

That makes a Skill closer to a small software artifact than to a long prompt. It has an activation contract, an execution path, supporting resources, and failure modes. If it is vague, it can be selected at the wrong time. If it is too large, it consumes context before the actual work begins. If it changes without review, the agent's behavior changes without an obvious code diff.

SolonCode's own skill-creator package provides a useful structure for treating Skills as reviewable assets. This article turns that structure into a practical workflow.

Start with the contract, not the prose

The smallest Skill package has a required SKILL.md file. Its frontmatter must define at least:

---
name: repository-release-notes
description: "This skill should be used when preparing release notes from a repository's merged changes and changelog entries."
license: Complete terms in LICENSE.txt
---

The important part is not the name alone. The description is the discovery contract. It tells the agent when this package is relevant.

A weak description says:

description: Helps with release notes.

A stronger description names the work and the evidence it expects:

description: This skill should be used when converting merged pull requests, changelog entries, and release labels into a concise repository release-notes draft.

The second version is still short, but it gives the selector more useful signals. It also avoids claiming that the Skill handles every kind of writing.

The skill-creator guidance explicitly recommends specific descriptions and a third-person form such as “This skill should be used when...”. That is a small metadata rule with a large operational effect: if the package is not selected reliably, the quality of the instructions inside it does not matter.

Keep the top-level instructions small

A Skill package can contain three kinds of supporting resources:

repository-release-notes/
├── SKILL.md
├── scripts/
│   └── collect_changes.py
├── references/
│   └── release-style.md
└── assets/
    └── release-template.md

Each directory has a different job.

scripts/ is for executable work that should be deterministic or is repeatedly rewritten.
references/ is for detailed material that should be loaded when the task needs it.
assets/ is for files used in the output, such as templates, icons, or starter files.

This is more than tidy packaging. It is a context-management strategy.

Put the essential procedure in SKILL.md: how to recognize the task, which steps must happen, and which supporting file to open. Put long schemas, examples, and policies in references/. Put reusable output material in assets/. The result follows progressive disclosure: metadata is always available, the Skill body is loaded when selected, and deeper resources are loaded only when needed.

A compact SKILL.md might look like this:

---
name: repository-release-notes
description: This skill should be used when converting merged pull requests, changelog entries, and release labels into a concise repository release-notes draft.
---

# Repository Release Notes

1. Inspect the repository's changelog and merged changes.
2. Load `references/release-style.md` before drafting.
3. Use `scripts/collect_changes.py` when a deterministic change list is needed.
4. Preserve links to source changes and separate verified facts from suggestions.
5. Render the result with `assets/release-template.md`.
6. Check the final draft against the repository's release style before returning it.

The file is not trying to contain the whole domain. It is routing the work.

Make examples executable or at least checkable

A Skill is easier to review when its instructions imply a fixture that can be checked.

For a release-notes Skill, a fixture could contain:

fixtures/release-case/
├── CHANGELOG.md
├── merged-changes.json
└── expected-draft.md

The fixture does not need to be part of the distributed Skill package. It can live in the repository that owns the Skill. The purpose is to answer concrete questions:

Does the description cause the Skill to be selected for the intended request?
Does the procedure tell the agent where to find evidence?
Does the output preserve links and uncertainty?
Does the template produce a usable result rather than a generic essay?

This is the same mindset used for code tests: make the expected behavior visible, then make regressions cheap to detect.

There is one important distinction. The documented skill-creator package describes the package shape and packaging validation; it does not claim that SolonCode automatically executes semantic tests for every Skill. Semantic checks remain the responsibility of the Skill author and the project that consumes it.

That boundary is healthy. Syntax and structure can be validated mechanically. Whether a workflow gives good answers requires task-specific fixtures and human review.

Use the documented creation path

When creating a new Skill from scratch, the source documents this initializer:

scripts/init_skill.py repository-release-notes --path ./skills

The initializer creates the Skill directory, a SKILL.md template, and example resource directories. After that, remove unused examples and replace the placeholders with the smallest useful package.

The workflow is deliberately staged:

understand examples
        ↓
plan scripts, references, and assets
        ↓
initialize the package
        ↓
write the contract and procedure
        ↓
run a real fixture
        ↓
package and review the result

This prevents a common failure mode: writing a large instruction file first and only later discovering that half of it belongs in a reference document or a deterministic script.

Package validation is a release gate

After editing, the documented packaging command is:

scripts/package_skill.py ./skills/repository-release-notes ./dist

The package step validates the YAML frontmatter, naming conventions, directory structure, description quality, and resource references before creating a zip archive.

That validation is useful, but it is not a substitute for behavioral review. A package can have valid frontmatter and still have an ambiguous trigger. It can have a correct directory structure and still instruct the agent to invent facts. Treat the package command as a release gate for structure, then run the fixture as a release gate for behavior.

A practical review checklist looks like this:

[ ] name is stable and descriptive
[ ] description says when the Skill should be used
[ ] SKILL.md contains the short procedure, not the whole encyclopedia
[ ] every referenced file exists
[ ] scripts have a deterministic reason to exist
[ ] references are loaded only when needed
[ ] assets are output resources, not hidden instructions
[ ] examples cover the important path and at least one failure path
[ ] package validation passes
[ ] a reviewer can explain how to roll back the change

The last item is easy to overlook. A Skill changes agent behavior. It should be possible to revert it by reverting a directory change or selecting the previous package, just as a code change can be rolled back to a known commit.

Review Skills in the SolonCode Web workflow

SolonCode exposes Skills as a managed part of the workspace rather than treating them as invisible prompt text. The Web settings code renders Skill names, descriptions, and paths for mounted sources, and provides management actions.

That makes a useful authoring loop possible:

edit the Skill in a workspace;
inspect its metadata and source location in the Web settings surface;
run a concrete task against a fixture;
revise the package;
refresh the runtime's Skill discovery when needed;
rerun the same fixture;
keep or revert the package based on the result.

The runtime reference used by SolonCode documents engine.refreshSkills() as the refresh operation. The exact refresh timing should still be verified in the running product and version being used; a source-level method name is not a promise that every client refreshes at the same moment.

This is where a Skill starts to feel like code review. The author can show the package, the fixture, and the observed result instead of saying only “the prompt seems to work.”

Use task queueing to run the review loop without losing your train of thought

Skill authoring often produces a sequence of related checks:

inspect the package;
run the fixture;
compare the output with the expected draft;
inspect the failure case;
update the description;
package the result again.

SolonCode's Web interface supports queued follow-up messages for this kind of loop. While a task is running, a follow-up can wait in the queue and run after the current task. The queue is persisted through /web/chat/queue and the session's queue-tasks.json; after a refresh, queued text is restored for review but is not automatically sent.

That last behavior matters. Restoring a queue should not unexpectedly start a chain of model calls. Cold restore hydrates the UI; the user explicitly resumes it.

Steering is a different tool. An Enter submission during a running task is sent to /web/chat/steer. The message first appears as pending, then becomes visible when the backend reports system.steer_applied. If the run changes or the steering mailbox is full, the message is demoted to the normal queue rather than silently discarded.

The distinction is useful when reviewing a Skill:

Steer = change the current investigation
Queue = run the next check after the current investigation

For example, if the agent is testing the wrong fixture, steer it: “Use the failure-case fixture instead.” If the current test is correct and you simply want the next comparison, queue: “Now compare the output with expected-draft.md.”

The implementation also gives steering a deliberate boundary. SteerInterceptor stores pending text in a transient session mailbox, injects it at a reasoning boundary, and does not interrupt an in-flight model stream or tool call. It guards the first turn and avoids injecting while the last assistant message still has open tool calls. If the task ends before the message is consumed, the backend emits a dropped event and the frontend moves it to the regular queue.

This is a good model for safe workflow control: immediate feedback does not have to mean unsafe interruption.

A small operating procedure for Skill changes

Here is a repeatable review sequence for a real Skill repository.

1. Read the current package

Record the name, description, instruction steps, and every referenced resource. Do not review only the prose; the trigger metadata is part of the behavior.

2. Identify one intended request and one near miss

Write a request that should select the Skill and another that should not. This tests whether the description is specific or merely enthusiastic.

3. Run the happy-path fixture

Use a small, known input and record the expected output shape. Preserve source links and mark any inference as an inference.

4. Queue the next check

While the first check is running, queue the failure-case comparison. Keep the current task focused rather than stuffing every future instruction into the active prompt.

5. Steer only when the current direction is wrong

If the agent starts inspecting the wrong file or uses the wrong fixture, steer it. Do not use steering as a replacement for a clearly ordered test plan.

6. Package-validate the change

Run the documented packaging command. Fix missing references, invalid metadata, or structural problems before asking anyone else to consume the package.

7. Review the diff and keep a rollback point

A Skill is behavior. Review it like behavior: what activates it, what it can cause the agent to do, and how to return to the previous version.

The larger lesson

The most useful Skills are not the longest ones. They are the ones with a precise activation contract, a short procedure, well-separated supporting material, and a checkable result.

SolonCode's package structure makes those boundaries visible:

SKILL.md explains what to do and when;
scripts/ makes repeatable work deterministic;
references/ keeps detailed knowledge available without bloating every run;
assets/ supplies reusable output material;
package validation catches structural mistakes;
fixtures and review catch behavioral mistakes;
steering and queueing let the author control an active review without losing the next planned check.

Once Skills are treated as code-like assets, “prompt tweaking” becomes an engineering loop: define, test, inspect, package, observe, and roll back when necessary.

Source reviewed: opensolon/soloncode

Key source paths:

soloncode-cli/release/skills/skill-creator/SKILL.md
soloncode-cli/src/main/java/org/noear/solon/codecli/portal/web/SteerInterceptor.java
soloncode-cli/src/main/resources/static/js/app-streaming.js
soloncode-cli/src/main/resources/static/js/app-settings-mounts.js
soloncode-cli/src/main/java/org/noear/solon/codecli/portal/web/WebController.java

One Agent Core, Six Entry Points: How SolonCode Reuses Its Runtime

Solon Framework — Mon, 31 Aug 2026 13:53:30 +0000

A coding agent rarely stays inside one interface.

A developer may want an interactive terminal for exploration, a browser for reviewing tool calls and Git changes, a desktop workspace for editing, a one-shot command for CI, a persistent process for an SDK, or an IDE connection through the Agent Client Protocol (ACP).

The easy implementation is to build a separate agent for each surface. The result is usually six versions of model selection, permissions, sessions, tools, and error handling that slowly drift apart.

SolonCode takes a different route. Its public Java source exposes six user-facing surfaces—interactive CLI, Web, Desktop, one-shot run, persistent stream, and ACP—backed by five explicit CLI modes plus the interactive fallback, all built around the same Agent composition.

That does not mean the six interfaces are identical. It means their product-specific adapters sit around a shared core instead of reimplementing the coding agent each time.

The architecture in one picture

At a high level, the design looks like this:

Interactive CLI ─┐
Web UI ──────────┤
Desktop ─────────┤
run ─────────────┼──> WorkspaceContext ──> HarnessEngine
stream ──────────┤          │                    │
ACP ─────────────┘          │                    ├─ models
                            │                    ├─ tools
                            ├─ sessions           ├─ skills / agents
                            ├─ loop scheduler     ├─ permissions
                            ├─ file watcher       └─ memory
                            └─ workspace settings

The important class is not a UI component. It is the workspace context assembled by the Java backend.

In Configurator.agentRuntime(...), SolonCode initializes the default workspace, asks WorkspaceManager for that context, captures the context's Loop scheduler, and returns the context's HarnessEngine. The command dispatcher then connects the selected entry path to that runtime.

There is an important precision here: this is a shared composition model, not a promise that every workspace in every process uses one JVM-global engine. SolonCode Web supports workspace-specific contexts. The architectural point is that those contexts are built through the same runtime path rather than each interface inventing its own agent stack.

1. Interactive CLI: the direct conversation adapter

With no special mode selected, SolonCode starts CliShell on an interactive thread.

soloncode cli

This is the most direct product surface: prompt, streaming response, tool activity, commands, Skills, and session continuity in a terminal. It is useful when the terminal is already the developer's main control plane.

The CLI adapter owns terminal behavior—welcome text, keyboard interaction, command completion, and rendering—but it does not need its own model registry or separate tool implementation. Those remain runtime concerns.

That separation matters for maintenance. Adding a tool to the runtime should not require rebuilding the tool six times just because users can reach it from six places.

2. Web: a richer view over workspace state

The Web entry path is selected with:

soloncode web 0

Passing 0 asks SolonCode to probe for an available ephemeral port. Unlike the default CLI path, Web mode explicitly enables HTTP and WebSocket support. It registers the Web gate and the controllers for chat, settings, Skills, models, MCP, OpenAPI, LSP, memory, authentication, and remote runs.

This is a good example of an adapter adding product value without replacing the core. The browser can provide things a terminal cannot express as comfortably:

file-tree navigation;
structured tool cards;
model and provider settings;
Skills management;
session controls;
Git status and diff review;
Loop task configuration;
real-time updates over WebSocket.

The browser is not “the agent.” It is a client and control surface around workspace-aware Agent execution.

The source also avoids turning HTTP into an accidental dependency of every mode. App disables HTTP by default and enables it only for modes that need it, such as web and serve. ACP explicitly keeps HTTP and WebSocket disabled because its transport is standard input/output.

That is a small but valuable boundary: a headless run should not quietly start a server just because the same application can also serve a browser UI.

3. Desktop: an IDE surface, not a second Agent backend

SolonCode Desktop combines a Tauri/React interface with the Java CLI backend.

For development, the documented flow starts the backend separately:

soloncode serve 4808

The Desktop client then connects over HTTP and WebSocket. Its UI adds Monaco editing, an integrated terminal, file operations, Git controls, local workspace management, and native application behavior.

The responsibilities are deliberately split:

React / TypeScript UI
  ├─ layout and editor UX
  ├─ Agent conversation UI
  └─ HTTP + WebSocket client

Tauri / Rust native layer
  ├─ filesystem operations
  ├─ integrated terminal
  └─ CLI process management

Java CLI backend (`soloncode serve`)
  ├─ Agent runtime
  ├─ models and tools
  ├─ sessions
  ├─ Skills and memory
  └─ workspace execution

Desktop therefore does not need to ship a second implementation of reasoning, tool permission rules, or model invocation. It specializes in the IDE experience.

This is also why “same core” should not be misread as “same UI.” Web and Desktop can expose different controls, persistence choices, and editing affordances while still delegating Agent work to the same backend architecture.

4. `run`: one prompt, one lifecycle, a useful exit code

Interactive products are only half the story. Automation needs a command that completes one task, can emit a machine-readable result, and exits with a meaningful status code.

That is the role of soloncode run:

soloncode run "Inspect this repository and return the three highest-risk modules" \
  --permission-mode plan \
  --output-format json \
  --max-turns 8

PrintMode makes the lifecycle explicit. It resolves a prompt from the argument or standard input, applies runtime options, resolves a session, runs the Agent stream to completion, renders the chosen output, and returns an explicit exit code.

The source distinguishes at least these outcomes:

0 success
1 execution error
2 maximum turns exceeded
3 missing prompt
4 budget exceeded

This makes run suitable for shell scripts and CI jobs because success is not inferred from a sentence in a chat transcript.

It also supports three output styles:

text for a human-readable final answer;
json for one result object;
stream-json for JSONL output during one run; initialization and final-result events are always emitted, while intermediate assistant and tool events require --verbose.

The last item needs careful wording. Streamed output does not make run a persistent multi-turn process. The implementation rejects persistent stream input in run and tells callers to use the dedicated stream command instead.

5. `stream`: a process that stays alive

soloncode stream is a different lifecycle, not an alias for run.

soloncode stream --verbose

It is designed for a parent process or SDK that communicates through JSONL while keeping the Agent process alive across turns. A persistent consumer can reuse context without forking a new Java process for every message.

This separation avoids an ambiguous command whose behavior changes depending on a hidden combination of flags:

run     = one task, then exit
stream  = persistent JSONL input/output channel

That distinction is especially useful for integration code. A CI step normally wants the determinism of run; an SDK bridge normally wants the process lifetime of stream.

The shared runtime still matters. Persistent transport does not require a second tool catalog or a reduced “automation agent.” It changes how prompts and events cross the process boundary.

6. ACP: translate Agent events instead of rebuilding the Agent

ACP is the protocol-facing entry path:

soloncode acp

AcpLink creates an ACP agent over standard input/output. When an ACP prompt arrives, it converts the request into a Solon AI Prompt, obtains an Agent session, and runs the request through the injected runtime's prompt–session–stream pipeline.

Then it translates runtime events into protocol updates:

plan events become ACP plan entries;
reasoning deltas can become thought updates;
tool starts become in-progress tool-call cards;
tool completions become completed or failed updates;
file edits can become structured diffs;
the final run event becomes the final ACP message.

This is adapter code in the best sense. ACP defines how an IDE or client sees the work, while HarnessEngine defines how the work is done.

Not every internal event is exposed. SolonCode filters internal task-dispatch, memory, and Goal tools from ACP tool cards. That is another sign of a deliberate boundary: sharing a runtime does not mean leaking every internal mechanism into every protocol.

What is actually shared?

“Shared core” can become vague architecture marketing, so it helps to name the concrete concerns.

Model selection and invocation

The adapters do not each implement provider calls. They select or pass model context into the Agent runtime.

Tools and permissions

File reads, edits, search, terminal execution, Web access, and extension tools belong to the runtime. Entry paths can change permission behavior—for example, a headless plan run denies write-oriented tools—but they apply that policy to the same tool system.

Sessions

Each adapter resolves sessions in a way appropriate to its lifecycle. An ACP session is not automatically the same identifier as a Web session, and a one-shot run may create its own print session. What is shared is the session abstraction and Agent execution path, not magical cross-client session synchronization.

Skills, agents, MCP, and memory

These capabilities are composed into the engine and workspace. An adapter can expose management UI or choose a stripped-down mode such as --bare, but it does not need to invent an incompatible extension model.

Workspace boundaries

The workspace context brings together the engine and workspace services. Web can manage more than the default context, which is why the safest architecture statement is “one composition path per workspace,” not “one global Agent object for everything.”

What remains adapter-specific?

A clean shared core does not erase product differences.

Entry path	Adapter-specific concern
Interactive CLI	terminal rendering, keyboard flow, slash commands
Web	HTTP/WebSocket, browser state, settings panels, Git and task UI
Desktop	native window, Monaco, terminal, local file and Git experience
`run`	one-shot lifecycle, output format, exit status, automation options
`stream`	persistent JSONL transport and turn interruption
ACP	protocol capabilities, session requests, structured plan/tool updates

That table is the design in practical terms: reuse the Agent, specialize the boundary.

Why this architecture is useful to users

Most users will never open Configurator.java, but they still feel the consequences of the design.

A feature can travel across surfaces

When a capability belongs to the core, a new client does not have to start from zero. It still needs adapter work and UI, but the model, tool, Skill, permission, and workspace foundations already exist.

Automation is not a fragile scrape of the UI

run, stream, and ACP are first-class entry paths. A script does not need to drive browser buttons, and an IDE does not need to parse colored terminal output.

Interfaces can stay focused

The CLI can remain fast and direct. Web can prioritize review and settings. Desktop can prioritize editing. ACP can prioritize protocol fidelity. They do not all need to become the same giant application.

Runtime behavior is easier to audit

The public dispatch path is visible in one place. A reviewer can trace which command enables HTTP, which adapter receives the runtime, and how protocol events are mapped.

A practical way to choose an entry path

Use the interface that matches the lifecycle of the work:

Choose interactive CLI when you are living in a terminal and want a direct conversation.
Choose Web when you want browser-based review, settings, sessions, Git visibility, and task controls.
Choose Desktop when Agent work should sit next to editing, files, terminal, and Git in one native workspace.
Choose run when a script or CI step has one bounded task and needs a result plus exit code.
Choose stream when a parent process needs a persistent JSONL conversation.
Choose ACP when an ACP-compatible client or IDE should receive structured plans, tool calls, diffs, and results.

The choice changes the interaction contract. It does not require choosing a different SolonCode Agent implementation.

The broader engineering lesson

Multi-interface Agent products have two bad extremes.

The first is duplication: every client builds its own Agent stack, and behavior drifts. The second is false uniformity: every client is forced through one UI-shaped API even when a terminal, CI process, desktop editor, and protocol client have different needs.

SolonCode's source shows a more useful middle path:

compose the Agent at the workspace layer;
keep models, tools, permissions, sessions, Skills, and memory in that core;
give each entry path a lifecycle-specific adapter;
enable network servers only where they are needed;
translate runtime events into the native language of each surface.

The result is not six identical products. It is one open Agent architecture with six honest boundaries.

Source reviewed: https://github.com/opensolon/soloncode

Key implementation paths:

soloncode-cli/src/main/java/org/noear/solon/codecli/Configurator.java
soloncode-cli/src/main/java/org/noear/solon/codecli/App.java
soloncode-cli/src/main/java/org/noear/solon/codecli/portal/printmode/PrintMode.java
soloncode-cli/src/main/java/org/noear/solon/codecli/portal/acp/AcpLink.java
soloncode-desktop/README.md

DEV Community: Solon Framework

Giving an AI Agent a Real Sandbox: Filesystem and Network Jail, in Java

Why not just run the agent in Docker?

The entry point is one class

Filesystem: two different policies, on purpose

Network: a proxy, not a firewall rule

The constructor signature changed — watch out for this

Windows needs a different call

Observability: violations are data, not just logs

Before you ship this: two operational gotchas

The mental model

References

MCP Without the Boilerplate: Solon AI's Annotation-Driven Server and Self-Healing Client

Why MCP, and why in-process?

The server: one annotation per capability

The client: McpClientProvider

Four channels, one builder

Self-healing connections

Caching and change notification

Tool allow-lists and deny-lists

Configuration-driven wiring

Gotchas I hit while reading the source

When does this matter?

References

Chunk by Meaning, Not Just Size: A Deep Dive into Solon AI's SemanticSplitter

Chunk by Meaning, Not Just Size: A Deep Dive into Solon AI’s SemanticSplitter

The splitter is an ingestion-stage component

What the default constructor configures

The algorithm is a sliding-window comparison

1. Sentence-like segmentation

2. Build a context window

3. Apply the threshold

4. Enforce a token-size fallback

Embedding cost is part of the design

Metadata is preserved, but chunk identity is not invented

How to evaluate it instead of guessing

Where Agent RAG fits

A practical decision guide

Closing thoughts

Sources

Beyond Token Streaming: Solon AI 4.1's Semantic Chat Events

call() and stream() now answer different questions

Nine groups provide the current routing layer

An event-phase END is not necessarily the end of the stream

Recover the final response from RESPONSE_END

The normalizer creates consistent stateful event boundaries

Tool execution introduces steps

Usage is a two-level aggregation problem

Errors, aborts, and cancellation are different

ERROR and Reactor onError

ABORT

Reactor cancellation

Event filtering is delivery policy, not aggregation policy

A provider dialect translates frames; it should not duplicate semantics

A practical migration checklist

What the tests establish

The architectural payoff

What SolonCode's Profile Backup Really Protects

Start with the asset model

Schema versioning is a gate, not authenticity

Settings are filtered by top-level group

“Secrets excluded” has a narrow meaning

Explicit plaintext export is a deliberate risk switch

Preview and commit are separate uploads

Resource limits help, but they are not a complete ZIP policy

Asset restore is additive and overwriting, not mirroring

Commit is not transactional

Reload is not the same as restart

What the current tests prove—and do not prove

The engineering lesson

Source paths

File Events Are Hints: Keeping SolonCode's Workspace Tree in Sync

The synchronization pipeline

One watcher, multiple roots

Recursive registration is part of correctness

Coalesce operations into a net effect

The event envelope is intentionally small

Apply structural changes in dependency order

Patch visible nodes; mark invisible branches dirty

Insert without redrawing siblings

The client: `McpClientProvider`

`call()` and `stream()` now answer different questions

An event-phase `END` is not necessarily the end of the stream

Recover the final response from `RESPONSE_END`

`ERROR` and Reactor `onError`

`ABORT`

`text`: a human-oriented result

`json`: one terminal object

`stream-json`: an observable event stream