DEV Community: Hagicode

Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice

Hagicode — Fri, 19 Jun 2026 01:50:20 +0000

Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice

This article discusses how to switch Reasonix 1.x, a local ACP CLI provider, to DeepSeek V4 in HagiCode. The focus isn't really on "getting it in," but rather on the semantic changes from Reasonix 0.x to 1.x—startup parameters were cut down to just one -model, credentials and policies moved to reasonix.toml. Let's walk through the pitfalls encountered and the verification path, bit by bit.

Background

Recently someone asked a pretty specific question: how to integrate Reasonix 1.x version to use DeepSeek V4 in HagiCode.

At first glance it looked like a configuration question, but digging into the code revealed it's actually a CLI semantic migration problem. Reasonix is a local ACP (Agent Communication Protocol) CLI within HagiCode's multi-Agent Provider system. Its position in HagiCode's three-tier architecture is clear:

HagiCode.Libs — ReasonixProvider, ReasonixOptions, wrapping reasonix acp process startup, ACP handshake, streaming notification mapping.
hagicode-core — ReasonixCliProvider thin adapter, AIProviderType.ReasonixCli = 12, ReasonixGrain, Hero parameter mapping, health monitoring.
web — OpenAPI types, visual mapping, Hero configuration forms, multilingual copy.

The entire integration chain is already implemented in the archived proposal openspec/changes/archive/2026-06-06-integrate-reasonix-agent-provider. So the question isn't "how to get Reasonix into the system" anymore, but "once it's in, how to switch the model to DeepSeek V4".

The key turning point is: Reasonix 1.x and 0.x have fundamentally different ACP bootstrap semantics. This change directly determines how you configure DeepSeek V4. After all, once semantics change, even if the surface looks similar, it's a different beast entirely.

I'll leave that hanging: to untangle this complexity of multiple providers and multiple models, HagiCode adopted a "field preservation, semantic migration" design at the Reasonix adaptation layer. I'll explain exactly why this trade-off was chosen later.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project.

HagiCode is an AI coding assistant project supporting multiple local/remote Agent Providers. Code is open sourced at HagiCode-org/site.

Analysis

1.x Cut Startup Parameters to Just One

Look directly at ReasonixProvider.BuildCommandArguments:

internal virtual IReadOnlyList<string> BuildCommandArguments(ReasonixOptions options)
{
    var arguments = new List<string> { "acp" };
    // Reasonix 1.x reduced ACP bootstrap to a transport-scoped provider selector.
    AppendOption(arguments, "-model", options.Model);
    foreach (var argument in NormalizeExtraArguments(options.ExtraArguments))
        arguments.Add(argument);
    return arguments;
}

That comment is the key: 1.x condensed ACP bootstrap to a "transport-scoped provider selector." In plain English—the only flag still meaningful at startup is -model.

Those legacy flags from the 0.x era are explicitly filtered out:

private static readonly HashSet<string> FilteredBootstrapFlags = new(StringComparer.OrdinalIgnoreCase)
{
    "-model", "-m", "--model",
    "-dir", "--dir",
    "-effort", "--effort",
    "-budget", "--budget",
    "-transcript", "--transcript",
    "-mcp", "--mcp",
    "-mcp-prefix", "--mcp-prefix",
    "-yolo", "--yolo",
    "--dangerously-skip-permissions",
    "--no-proxy"
};

Unit tests directly prove this. Pass in a bunch of legacy flags, the command line comes out clean, no errors, just silently dropped:

arguments.ShouldBe(
[
    "acp",
    "-model", "deepseek-v4-flash"
]);

ReasonixOptions Fields Still There, But Semantics Changed

Here's an interesting design choice. Fields like Effort, BudgetUsd, TranscriptPath, EnableYolo, McpServerSpecs, McpPrefix in ReasonixOptions are all preserved, but each comment honestly states "Reasonix 1.x ACP no longer accepts ... so this value is currently ignored".

This is a classic field preservation, semantic migration pattern: caller contracts aren't broken (0.x code still compiles, still passes values), but at runtime these values are silently dropped. Policy-type things (permissions, MCP plugins, proxy) are required to move to reasonix.toml.

To put it another way, it's like your original light switch is still on the wall, but the renovation guy changed the wiring. Now the switch is just decoration, the real lighting control moved to the smart home panel. The switch looks unchanged, pressing it doesn't error out, but the light just doesn't turn on.

So the core action for integrating DeepSeek V4 is actually just one sentence: pass the model id through the -model selector, configure credentials/endpoint in reasonix.toml.

How DeepSeek V4 Gets In

In HagiCode's tests and README, the DeepSeek series uses the standard pattern through the Model field:

var reasonixOptions = new ReasonixOptions
{
    WorkingDirectory = "/path/to/repo",
    Model = "deepseek-flash",
    SessionId = "reasonix-session-123"
};

Tests repeatedly show Model = "deepseek-v4-flash", corresponding to the generated command line reasonix acp -model deepseek-v4-flash. The specific model id (deepseek-v4-flash, deepseek-flash, etc.) should follow the Reasonix 1.x version you installed and the provider aliases registered in reasonix.toml—after all, whether an alias is real or not, Reasonix knows best.

Working Directory and Session Recovery Go Through ACP, Not CLI Flags

This is the second semantic change in 1.x, easy to get confused about. In 0.x you used --dir to specify working directory, in 1.x it changed to using session/new / session/load within the ACP protocol:

var sessionHandle = await sessionClient.StartSessionAsync(
    workingDirectory,
    options.SessionId,
    model: null,   // Model selection completely determined by startup -model
    startupCts.Token);

Note that the model parameter in StartSessionAsync passes null—model selection is completely determined by -model at startup, session level no longer overrides the model. SessionId is still a provider-native continuity hint, used only to resume sessions.

Solution

Putting the above analysis together into an executable path, let's walk through four steps.

Step 1: Install Reasonix CLI

Reasonix is a locally installed, IsPubliclyInstallable: false provider, can't be installed via npm publicly. First put the reasonix executable in PATH. After installing, verify with HagiCode.Libs' built-in console:

# Run Ping scenario, execute reasonix acp handshake and report version
dotnet run --project src/HagiCode.Libs.Reasonix.Console -- --test-provider reasonix

If handshake fails, it's usually one of two cases: either PATH didn't find reasonix, or reasonix.toml isn't configured. There aren't really any other reasons.

Step 2: Configure DeepSeek V4 Credentials in reasonix.toml

1.x no longer accepts startup flags like --api-key, --base-url. Model provider endpoint, API key, proxy policies all need to be written to reasonix.toml. Configuration roughly includes:

DeepSeek V4 API endpoint
DeepSeek API key
Aliases you want to expose to the -model selector (like deepseek-v4-flash)

Specific field names should follow the documentation of your installed Reasonix version. HagiCode's side only cares about passing through -model deepseek-v4-flash, how this alias resolves to the actual model is Reasonix's business—responsibility boundaries are clearly drawn, don't cross lines.

Step 3: Configure HagiCode's ProviderConfiguration

The resolution priority in backend ReasonixCliProvider.ResolveModel is: request.Model takes priority, otherwise fall back to _config.Model:

private string? ResolveModel(AIRequest request)
{
    var model = string.IsNullOrWhiteSpace(request.Model)
        ? _config.Model
        : request.Model;
    return string.IsNullOrWhiteSpace(model) ? null : model.Trim();
}

So in appsettings or runtime config, set the provider's Model to DeepSeek V4's alias:

{
  "AIProvider": {
    "Providers": {
      "ReasonixCli": {
        "Type": "ReasonixCli",
        "Model": "deepseek-v4-flash",
        "Settings": {}
      }
    }
  }
}

Here's a trap that's easy to step in: Settings can only hold keys within the whitelist:

private static readonly IReadOnlyList<string> SupportedSettingKeys =
[
    "effort", "budgetUsd", "transcriptPath",
    "enableYolo", "arguments", "startupTimeoutMs", "reasoning"
];

ValidateConfigurationOverrides will directly reject keys outside the whitelist. And most of these keys are ignored in 1.x (corresponding to those ignored fields in ReasonixOptions), so never stuff DeepSeek credentials into Settings, that's not where they belong, credentials go to reasonix.toml.

Step 4: Use Console for End-to-End Verification

After configuration, run the full suite with Reasonix's dedicated console, explicitly specifying the model as DeepSeek V4:

# Default suite: four scenarios - Ping / Simple Prompt / Complex Prompt / Session Resume
dotnet run --project src/HagiCode.Libs.Reasonix.Console -- \
  --test-provider-full --model deepseek-v4-flash --repo .

If all four scenarios pass green, the model selector, ACP handshake, streaming notifications, session recovery—the entire chain is connected. Green means peace of mind.

Practice

How to Fill the Hero Configuration Form in Frontend

If you go through HagiCode's Hero career UI instead of directly modifying appsettings, after selecting Reasonix in HeroCliEquipmentForm, the form fields are:

binary: default reasonix
model: fill deepseek-v4-flash (key field for switching to DeepSeek V4)
effort: none / low / medium / high (ignored in 1.x, but UI still keeps it)
budgetUsd: number (ignored in 1.x)
transcriptPath: text (ignored in 1.x)
enableYolo: boolean (ignored in 1.x, permissions go to toml)
arguments: extra parameters passed through to ACP
startupTimeoutMs: default 15000

Actually, only the model field affects DeepSeek V4 behavior, the rest are just decoration under 1.x. This is also HagiCode's "field preservation, semantic migration" design reflected in the UI—the form doesn't break old user habits, but the fields that actually take effect are converged.

Session Binding and Recovery

ReasonixCliProvider uses ConcurrentDictionary<string, string> to maintain session bindings, binding key is calculated from sessionId, working directory, executable path, and model:

var bindingKey = NormalizedAcpCliAdapter.BuildBindingKey(
    effectiveRequest.CessionId,
    options.WorkingDirectory,
    options.ExecutablePath,
    options.Model);

This means if you switch models mid-session in the same session, the binding key changes and it's treated as a new session. So after integrating DeepSeek V4, keep the model alias stable throughout the session lifecycle, otherwise resume will break. I learned this the hard way through actual testing—blood and tears lesson, still remember the taste.

Monitoring and Degradation

Reasonix uses the Provider strategy (not Grain strategy) in AgentCliMonitoringRegistry, since it might not be installed:

new AgentCliMonitoringDescriptor
{
    CliId = "reasonix",
    DisplayName = "Reasonix",
    ProviderType = AIProviderType.ReasonixCli,
    Strategy = Provider, // ping-based, via PATH discovery
    ExecutableCandidates = ["reasonix"]
}

Frontend health checks show whether Reasonix is available. If reasonix isn't in PATH, the UI gracefully degrades to "unavailable"—this logic is built in, no need to worry about it yourself.

Several Practical Points to Note

Authenticity of Model Aliases: deepseek-v4-flash must be a real alias registered in reasonix.toml, otherwise ACP handshake passes but sending prompts still fails. Verify with console first before going to Hero, don't cut corners.
Don't Use arguments to Pass Legacy Flags: NormalizeExtraArguments filters out --effort, --budget, etc., passing them is futile, wasted effort.
Credentials Only in toml: API key, endpoint, proxy, MCP plugins all go in reasonix.toml, HagiCode's side Settings whitelist doesn't have these fields at all.
startupTimeoutMs is Adjustable: If DeepSeek V4 cold start is slow, raise startupTimeoutMs from default 15000, this field is recognized in 1.x.
Economic System Maps to Claude Bucket: Frontend resolveEconomicSystemByExecutorType maps Reasonix to the 'claude' bucket, purely for display, doesn't affect billing.

A Minimal Verification Path

If you just want to confirm DeepSeek V4 works quickly without touching Hero UI:

Install reasonix, configure reasonix.toml (DeepSeek endpoint + key + alias)
Set ReasonixCli.Model = "deepseek-v4-flash" in appsettings
Run dotnet run --project src/HagiCode.Libs.Reasonix.Console -- --test-provider-full --model deepseek-v4-flash
All four scenarios green, integration complete

Summary

Returning to the original question—"how to integrate Reasonix 1.x to use DeepSeek v4".

The answer is actually just one sentence: pass the model alias through the -model selector, configure credentials and policies in reasonix.toml, don't count on CLI flags.

Behind that one sentence is a pretty clean semantic convergence by Reasonix 1.x: startup parameters cut to just -model, working directory and session recovery moved into ACP protocol, policies all sunk into toml. HagiCode's adaptation layer didn't fight this change head-on, but chose the gentle "field preservation, semantic migration" route—old code still compiles, still passes values, silently ignored at runtime, converging effective switches to just -model.

The benefit of this trade-off is smooth migration, the cost is documentation needs to be clear—which is why this article exists. Just remember three things:

Models go through -model, DeepSeek V4 is -model deepseek-v4-flash
Credentials go to toml, don't stuff them into Settings
Don't switch models mid-session, binding key changes, resume breaks

HagiCode chose to design the Reasonix adaptation layer this way essentially because it needs to accommodate multiple providers, multiple model versions, multiple deployment forms. This complexity of multiple languages, multiple platforms is exactly why we repeatedly polish the provider adaptation strategy in HagiCode.

References

Reasonix Provider implementation: repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixProvider.cs
Reasonix Options field semantics: repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixOptions.cs
Backend thin adapter: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/ReasonixCliProvider.cs
Integration proposal archive: openspec/changes/archive/2026-06-06-integrate-reasonix-agent-provider
Backend spec: openspec/specs/reasonix-backend-integration/spec.md
Unit tests (including deepseek-v4-flash cases): repos/Hagicode.Libs/tests/HagiCode.Libs.Providers.Tests/ReasonixProviderTests.cs
HagiCode official site: hagicode.com

Summary

Around "Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice," a more solid approach is to first gradually get key configurations, dependency boundaries, and implementation paths working, then fill in optimization details.

When goals, steps, and acceptance criteria are clear, this type of solution usually flows more smoothly into actual delivery.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-19-reasonix-1x-deepseek-v4-acp-integration%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Pi Agent Integration: Message Parsing, Retry, and Cancellation

Hagicode — Fri, 19 Jun 2026 01:12:00 +0000

Pi Agent Integration: Message Parsing, Retry, and Cancellation

When integrating a CLI-based AI agent, you can't avoid three things: how to translate its private event stream into stable messages, who's responsible for retry after failures, and how to cleanly stop the process when users click cancel. These three things essentially boil down to "clarifying responsibilities"—it's simple in theory, but you only realize how deep the water is when you actually do it.

Background

Recently, I've been working on an AI coding assistant project, and one of the agents to integrate is pi. It's a TUI/CLI coding agent that outputs JSON events line by line to stdout when running. Sounds simple—spawn the process, read output, parse it—but when you actually start, you realize "integrating an agent CLI" is completely different from "integrating a regular CLI."

With a regular CLI, you read stdout, get an exit code, and that's it. But agent CLIs have three particularly headache-inducing characteristics:

First, its event stream is a private protocol. turn_start, session, message_update, message_end, turn_end, agent_end—these are defined by pi itself, not any industry standard. Every upper layer that wants to consume it has to handle it separately, effectively leaking pi's internal details everywhere. It's like looking at someone from a distance—you think you see them clearly, but you're only seeing the side they want to show you.

Second, its failure semantics are particularly ambiguous. The agent might encounter network jitter, model rate limiting, or process crashes while running. Should it retry? Where to retry? Will retry mess up the session state that's already half-output? This is an architectural decision, not something you can solve by casually writing a for loop.

Third, it's long-running and interruptible. A single turn might run for tens of seconds or even minutes, and users might want to cancel at any time. When canceled, the process can't become an orphan, tool calls can't be left half-finished, and already output content can't be lost. The water here is much deeper than imagined.

To solve these pain points, we spent some time straightening out the integration path. I'll get into specifics later, but here's a spoiler: the real difficulty isn't in "spawning the process," but in "clarifying responsibilities."

About HagiCode

The solution shared in this article comes from the HagiCode project—an AI coding assistant that supports multiple models and multiple agent CLI backends. GitHub repository: HagiCode-org/site, feel free to star it. All the code and all the pitfalls mentioned below are actually running in this project. Writing this out is just leaving myself a memory.

Overall Layering

HagiCode splits AI capability integration into two layers:

The bottom layer is Hagicode.Libs, providing reusable provider primitives ICliProvider<TOptions>, specifically responsible for "spawning a CLI agent and normalizing its output into a shared message stream."
The upper layer is hagicode-core, providing project-level thin adapters IAIProvider, responsible for "translating business requests into provider parameters, consuming shared message streams, and exposing unified streaming chunks externally."

Pi's integration follows this path. The bottom layer PiProvider spawns the pi process, reads the JSON event stream, and normalizes it into shared messages; the upper layer PiCliProvider translates AIRequest into PiOptions, consumes CliMessage, and outputs AIStreamingChunk.

These three things—message parsing, retry, cancellation—fall into three different places: PiJsonEventMapper, a seemingly strange archiving proposal, and CliProcessManager. Let's talk about each one.

Message Parsing: Converting Pi's Private Events to Shared Messages

pi outputs JSON events line by line under --mode json --print. This event set is private to pi and must not be leaked directly to upper layers, otherwise every consumer would couple to pi's internal details, and the entire project would follow pi's upgrades when its event structure changes. This kind of leakage is similar to writing your thoughts on your face—others find it tiring to look at, and you're not necessarily comfortable either.

We use PiJsonEventMapper as a translation layer to normalize pi's events into shared CliMessage. CliMessage is defined in HagiCode.Libs.Core/Transport/CliMessage.cs with a very simple structure—just a (Type, Content) record. The mapping relationship is roughly as follows:

pi event	shared message	purpose
`session`	`session.started` / `session.resumed`	session lifecycle
`message_update` (text type)	`assistant`	streaming body incremental
`message_update` (thinking type)	`assistant.thought`	thought chain
`message_update` (tool type)	`tool.call` / `tool.update`	tool call initiation
`message_end` / `turn_end` (toolResult)	`tool.completed` / `tool.failed`	tool result
`turn_end` / `agent_end`	`terminal.completed`	current turn end
non-zero exit / parse failure	`terminal.failed`	terminal state failure

This table is just a quick reference, but it contains two key techniques that were figured out after stumbling into pitfalls—worth expanding on.

Technique One: Converting Cumulative Snapshot to Delta

This is the easiest place to crash. pi's message_update event doesn't send increments, but cumulative full text—every time a token comes, it resends the "complete text so far."

If you forward received content directly to the frontend, users will see content repeated: the first is "you", the second is "hello", the third is "hello,", the fourth is "hello, wor"... The frontend will think these are four independent outputs. Repetition is fresh the first time you see it, but boring the tenth time.

The solution is prefix comparison to calculate the true delta:

// Key: pi sends cumulative snapshot, not increment
// Use prefix comparison to extract the delta, otherwise frontend sees repeated content
if (text.StartsWith(_lastAssistantTextSnapshot, StringComparison.Ordinal))
{
    var delta = text[_lastAssistantTextSnapshot.Length..];
    _lastAssistantTextSnapshot = text;
    return delta.Length == 0 ? null : delta;
}

There's another hidden pitfall here: cross-turn prefix replay. After tool calls end and the assistant continues speaking, pi will replay that previous text from the beginning again. If you only keep a global snapshot, you'll treat the replayed content as increments, causing repetition after tool calls. PiProviderTests has a dedicated test case ExecuteAsync_deduplicates_replayed_assistant_prefix_after_tool_turns covering this scenario. In other words, snapshots before and after tool calls need aligned processing, not independent handling.

Technique Two: Buffer Thinking Until Turn End

Thought chains (thinking) can't be output as soon as each token is received. pi stuffs a bunch of thinking fragments in the middle of tool calls. If forwarded in real time, the stream order becomes a mess—一会儿是 assistant 正文，一会儿是思考碎片，一会儿又是 tool.call。Does this make sense? It doesn't really, just adding confusion.

Our approach: when receiving thinking events, first put them in BufferThinkingSnapshot for temporary storage, and wait until message_end or turn_end with stopReason != "toolUse", then uniformly DrainBufferedThinkingMessages. This way, thinking fragments in the middle of tool calls won't pollute the main stream, and the complete thought process is given all at once when the turn ends.

Fault Tolerance: Bad Lines Can't Crash the Stream

Agent CLI isn't the ideal system from textbooks. It occasionally spits out a non-JSON line, or a JSON without a type field. If you throw an exception here, the entire stream dies and users see nothing. The real world isn't always perfect—who can guarantee every line is well-behaved?

Our strategy: any line that fails to parse doesn't interrupt the stream, but is collected into _invalidOutputLines. After the process ends, in Complete(), these "bad lines" are spliced into the diagnostic text of terminal.failed. This way, when users see errors, they can directly see what garbage pi actually output, not a dry "parse error."

Retry: If Provider Layer Doesn't Do It, Who Does?

This is the easiest pitfall in the entire integration. Intuitively "integrating a CLI should include retry," but HagiCode in an archiving proposal actively removed all automatic retry from the provider layer. The proposal is called remove-provider-auto-retry-support.

Why No Automatic Retry

The proposal background is written very bluntly. Retry logic was originally scattered in two places: one copy in Hagicode.Libs (OpenCode-style fresh-runtime replay), another in hagicode-core (ProviderErrorAutoRetryCoordinator). Both sides did their own thing, making "whether to retry" a hidden implicit behavior inside the provider, secretly changing failure timing, session continuation method, and chat state flow.

Think about it and your head hurts: user sends a message, provider internally retries three times itself, first two fail, third succeeds. Upper layer has no idea what happened in the middle, session state, token counting, UI progress all don't match. This kind of implicit behavior is chronic poison in architecture.

So the boundary was converged into one sentence:

provider converges to single-attempt semantics, caller needs to treat non-retry state as normal single-execution result.

What Does This Mean for PiProvider

In code, it's three things:

PiOptions has no retry-related fields—no maxAttempts, no retryDelay, no retryClassifier.
ExecuteAsync ends after one pi process run completes, failures directly give terminal.failed.
Classifiers previously serving automatic retry (ClaudeCodeRetryableTerminalFailureClassifier, CodexRetryableTerminalFailureClassifier, etc.)—if they purely served automatic retry—are all removed from the active path.

But please note, retry capability hasn't disappeared, just moved up. The proposal explicitly writes "leaving a stable boundary for higher layers to uniformly take over retry later." The DTO for providerErrorAutoRetry configuration item, normalization, serialization, frontend settings page round-trip are all preserved, it just no longer drives provider execution. Some things aren't really unwanted, just kept in a different way.

What If You Want to Retry

If you want to add retry on top of pi, the correct approach is to do it at the caller of PiCliProvider—for example, your session orchestration layer (in HagiCode it's Orleans's SessionGrain, frontend might be chat orchestration layer). After getting terminal.failed, judge yourself whether it's retryable, decide delay and count yourself, then send ExecuteAsync again.

A minimal viable pattern looks like this:

// Retry logic at caller, don't stuff back into PiProvider
// Otherwise breaks the "single-attempt" boundary just established by provider
async Task<AIResponse> ExecuteWithRetryAsync(AIRequest req, int maxAttempts, CancellationToken ct)
{
    for (var attempt = 1; ; attempt++)
    {
        var response = await provider.ExecuteAsync(req, ct);

        // Return on success or reaching limit
        if (response.FinishReason != FinishReason.Unknown || attempt >= maxAttempts)
            return response;

        // Only retry retryable terminal failures (network, 5xx, process crash)
        // model rejected, auth failure这类重试也无意义，别重试
        await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)), ct);
    }
}

The classification logic for judging "retryable" is no longer in the provider, caller defines it themselves. providerErrorAutoRetry configuration (maxAttempts, retryDelay, enabled) can still be read from the frontend settings page, but what actually drives retry is your orchestration layer, not PiProvider. Repeat this three times.

Cancellation: Token Pass-through + Three-stage Shutdown

For cancellation, PiProvider almost doesn't implement anything itself, fully delegating to CliProcessManager. PiProvider only handles two things: passing CancellationToken down, and cleanup on exception.

Full-chain Pass-through

The chain looks like this, passing all the way down:

调用方 CancellationToken
  → PiCliProvider.StreamCoreAsync(cancellationToken)
  → PiProvider.ExecuteProcessAsync([EnumeratorCancellation] cancellationToken)
  → ReadLineAsync(cancellationToken) / WaitForExitAsync(cancellationToken)
  → 异常时 _processManager.StopAsync(handle, CancellationToken.None)

Note the last line: cleanup uses CancellationToken.None, not the token the user passed in. This is a detail, but extremely important.

The reason is: the user's token is already canceled. If you use this already-canceled token for cleanup, the cleanup task will be canceled immediately, and the process becomes an orphan—pi still running in the background, no one collecting it, CPU and memory occupied for nothing. So cleanup must use CancellationToken.None, ensuring cleanup actions definitely complete. It's like with people—some things need proper cleanup after they completely stop, otherwise it's just leaving a mess.

Three-stage Progressive Shutdown

CliProcessManager.StopProcessAsync is a three-stage progressive shutdown process, with time constants defined at the top of the file:

// 优雅停止的耐心：先给进程自己收尾的时间
private static readonly TimeSpan GracefulStopTimeout = TimeSpan.FromSeconds(2);
// 强制 kill 后等待进程真正退出的耐心
private static readonly TimeSpan StopWaitTimeout = TimeSpan.FromSeconds(5);

The three stages progress like this:

Interrupt signal. TryInterruptAsync first writes a \u0003 (Ctrl+C character) to stdin, and on Unix additionally does kill -INT <pid>. This step is to let pi gracefully end itself—it can perceive the interrupt and wrap up what it's writing.
Graceful wait. Wait at most 2 seconds to see if the process exits on its own.
Force kill. If it hasn't exited, directly Process.Kill(entireProcessTree: true) to kill the entire process tree together, then wait at most 5 seconds to confirm it's really dead.

Why entireProcessTree: true? Because pi spawns child processes when running tools—for example, local model processes routed by provider, bash subprocesses running. Killing only the parent process leaves child processes as orphans continuing to run. Killing the whole tree together is clean.

Under Windows there's no SIGINT, can only rely on Ctrl+C character, so cross-platform behavior will differ, keep this in mind.

PiProvider's Exception Cleanup

PiProvider's ExecuteProcessAsync when ReadLineAsync throws an exception, uses ExceptionDispatchInfo.Capture to temporarily store the exception, jumps out of the loop to call StopAsync to clean up the process, then pendingException.Throw() rethrows the original exception to the upper layer.

Why store then throw? Because if you throw directly, the process hasn't been recycled yet and becomes an orphan; if you throw before StopAsync, cleanup logic doesn't run at all. Store it temporarily, first guarantee the process is definitely recycled, then preserve the original OperationCanceledException semantics completely for the caller—caller gets this exception and can judge "oh, user actively canceled" not "something went wrong."

Unified Contract for Startup Failures

There's another detail worth mentioning separately. Process startup failure—for example, pi executable doesn't exist, wrong permissions—PiProvider doesn't throw exceptions, but synthesizes a terminal.failed message, then yield break.

Why do this? Because if you throw exceptions, upper layer consumers have to handle two completely different semantics: one is "normal messages during streaming consumption," the other is "exceptions thrown before streaming starts." This makes the consumer's await foreach particularly hard to write.

After unifying to "always give you messages first, then end the stream," consumer logic is consistent: getting terminal.failed counts as failure, getting terminal.completed counts as success, no need for try/catch branching. This is a small but important design decision, stabilizing the contract.

Practice: Correct Way to Consume Streams

Referencing PiScenarioMessageReader (libs console test scenario) and PiCliProvider.StreamCoreAsync (core thin adapter) in HagiCode, consumers look roughly like this:

await foreach (var message in provider.ExecuteAsync(options, prompt, cancellationToken))
{
    // 1. 短路处理失败，别再处理后续消息
    if (NormalizedAcpCliAdapter.TryGetFailureMessage(message.Content, out var failure))
    {
        yield return new AIStreamingChunk { Type = StreamingChunkType.Error, ErrorMessage = failure };
        yield break;   // stream ends after terminal.failed
    }

    // 2. assistant 文本是 cumulative snapshot，自己再做一次增量计算
    if (message.Type == "assistant" && TryGetText(message.Content, out var text))
    {
        var delta = ReconcileSnapshot(text);  // 前缀比对
        if (!string.IsNullOrEmpty(delta)) yield return Chunk(delta);
    }

    // 3. terminal.completed 是唯一可靠的"结束"信号
    if (message.Type == "terminal.completed") break;
}

Common Pitfalls Quick Reference

Organizing all the pitfalls encountered along the way into a table, for future reference:

现象	原因	处理
前端看到 assistant 文本重复	没做 cumulative 转 delta	用 `ReconcileAssistantTextSnapshot` 做前缀比对
取消后进程还在跑	清理用了已经取消的 token	改用 `CancellationToken.None` 做清理
重试不生效	把重试写进了 PiProvider，但 provider 是单次尝试语义	上移到调用方编排层
pi 报错信息丢失	没读 `terminal.failed` 的诊断字段	完整透传 `text` / `invalid_output_lines` / `stderr`
工具调用中途收到思考碎片	直接转发了 thinking 事件	缓冲到 turn 结束再 `DrainBufferedThinkingMessages`

How to Verify

The libs layer uses StubCliProcessManager to mock processes, with unit tests covering pure logic like parameter construction, event normalization, incremental deduplication, failure pass-through. The real CLI path uses HAGICODE_REAL_CLI_TESTS environment variable to opt-in, running trip scenarios with real models. The core layer's PiCliProviderTests verifies the thin adapter's AIStreamingChunk projection and session binding.

# 在 Hagicode.Libs 仓库跑 Pi 相关单测
dotnet test --filter "FullyQualifiedName~PiProviderTests"

# 跑真实 CLI 集成测试（需要本地装好 pi）
HAGICODE_REAL_CLI_TESTS=1 dotnet test --filter "FullyQualifiedName~PiProviderTests.RealCli"

Summary

Putting these three things together, the mental model for integrating pi actually boils down to one sentence: let each layer do only its own thing.

Message parsing is handed to PiJsonEventMapper: private events are normalized into shared CliMessage, cumulative snapshots converted to deltas, thinking buffered until turn end.
Retry is handed to the caller: provider does single attempts, whoever wants retry does it at the upper layer themselves, configuration is preserved but no longer drives provider.
Cancellation is handed to CliProcessManager: CancellationToken is passed through the full chain, cleanup uses CancellationToken.None, three-stage progressive shutdown (interrupt signal → graceful wait → force kill entire process tree).

After these boundaries are clearly drawn, integrating a new agent CLI almost becomes pipeline work—you just need to write a new XxxProvider and XxxJsonEventMapper, and cross-cutting logic like retry, cancellation, message contracts, error handling are all reused. This is also the fundamental reason why HagiCode can simultaneously support multiple agent CLI backends (claude code, codex, pi, gemini cli, etc.) without getting messy.

Let me say that most important boundary one more time: don't add retry at the provider layer. Once you understand this, integrating agent CLI is more than halfway done...

Summary

Returning to the theme "Pi Agent Integration: Message Parsing, Retry, and Cancellation," what's really worth repeatedly confirming isn't scattered techniques, but whether constraints, implementation boundaries, and engineering trade-offs have been clearly seen.

As long as the judgment bases in this article are settled into stable checklist items, you can make reliable decisions faster when facing similar problems in the future.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-19-pi-agent-integration-message-parsing-retry-cancel%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How to Use Upptime to Build Your Own Status Page for Free

Hagicode — Thu, 18 Jun 2026 05:30:22 +0000

How to Use Upptime to Build Your Own Status Page for Free

Move monitoring entirely into a GitHub repo—Actions as probes, the repo as a database, Pages as a CDN, and Issues as an event log. Zero servers, zero monthly fees, yet somehow you end up with a status page that you can view, query, and trace. Call it black magic or the wisdom of the frugal—either way, it runs.

Background

When operating a small product matrix consisting of over a dozen external services, "is it actually working" became a common refrain. Customers report they can't access it, you SSH in and curl once to find it's fine; a few minutes later it goes down, but this time you weren't watching. Commercial monitoring (Pingdom, UptimeRobot's premium tier, Datadog) can certainly solve this, but they charge either by site or by request count—for an indie developer, neither cost nor mental burden is quite worth it.

More importantly, users need to be able to check the status page themselves. Ideally, one domain (say status.hagicode.com) would display real-time availability for each service, response time curves, historical events, and automatically log incidents when failures occur with automatic notifications. The traditional approach requires four pieces—a server running cron, a database storing historical data, a frontend site, and a CDN. Once you lay out these four, operational costs immediately outweigh the services being monitored—using a sledgehammer to crack a nut, and even the nut feels crowded.

To address these pain points, we made a decision: move the entire monitoring solution directly to GitHub. This decision brought changes larger than you might imagine—I'll get to that gradually.

About HagiCode

The solution shared in this article comes from our experience building HagiCode. HagiCode is an AI code assistant project that exposes over a dozen public services including web pages, documentation sites, and download endpoints, driven by the main repository HagiCode-org/site. These sites must remain stable and available, so status monitoring is not optional for us—it's a necessity. The Upptime solution below is exactly what HagiCode's production environment uses—I didn't make this up.

Analysis: How Upptime Actually Works

Upptime is essentially a GitHub repository template plus six workflows generated by that template. The key to understanding it is seeing clearly "who calls whom, when, and produces what that lands where." Break it apart and it's not so mysterious.

Data Flow: One Configuration File Drives Everything

The entire system revolves around a single declarative configuration file .upptimerc.yml. HagiCode's actual configuration structure looks roughly like this:

owner: HagiCode-org
repo: upptime

sites:
  - name: HagiCode Website
    url: https://hagicode.com
  - name: HagiCode Docs
    url: https://docs.hagicode.com
  - name: Server Package Index
    url: https://index.hagicode.com/server/index.json
  # ... 14 sites total

status-website:
  cname: status.hagicode.com
  logoUrl: https://raw.githubusercontent.com/HagiCode-org/upptime/master/assets/upptime-icon.svg
  name: HagiCode Status
  introTitle: "**HagiCode Status**"
  introMessage: Real-time availability tracking for public HagiCode websites and download endpoints.
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

Two points here are worth calling out. First, sites can monitor both web pages (returning HTML) and pure JSON endpoints (like index.json)—Upptime only cares about HTTP status codes and response time, not content validation. Second, cname points to status.hagicode.com, which requires you to own that domain and configure DNS to point to GitHub Pages—after all, freebies aside, you still need to provide your own domain.

The Division of Six Workflows

All files under .github/workflows/ have a warning at the top Do not edit this file directly!—they're auto-updated weekly by the template; you only need to modify .upptimerc.yml. Each workflow is triggered by cron, calling different subcommands of the same action upptime/uptime-monitor@v1.42.6 with clear division of labor, which is actually quite reassuring:

Workflow	cron	command	purpose
`uptime.yml`	`/5 * * *`	`update`	probe every 5 minutes, write `history/*.yml`
`response-time.yml`	—	`response-time`	calculate response time statistics
`graphs.yml`	—	`graphs`	generate day/week/month/year PNG curves
`summary.yml`	—	`summary`	update status table in README
`site.yml`	`0 1 * * *`	`site`	build static site daily, deploy to Pages
`update-template.yml`	`0 0 * * *`	—	sync upstream template weekly

The core snippet of uptime.yml shows how the "probe" runs:

on:
  schedule:
    - cron: "*/5 * * * *"
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GH_PAT || github.token }}
      - name: Check endpoint status
        uses: upptime/uptime-monitor@v1.42.6
        with:
          command: "update"
        env:
          GH_PAT: ${{ secrets.GH_PAT || github.token }}
          SECRETS_CONTEXT: ${{ toJson(secrets) }}

site.yml adds one more step, using peaceiris/actions-gh-pages@v4 to push build artifacts to the gh-pages branch:

- uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GH_PAT || github.token }}
    publish_dir: "site/status-page/__sapper__/export/"
    user_name: "Upptime Bot"
    user_email: "73812536+upptime-bot@users.noreply.github.com"

Data Persistence: Files as Database

Monitoring results aren't stored in a database; instead they're committed back to the repository as files. This sounds a bit wild, but it's actually solid in practice. Each site produces three types of artifacts.

Status snapshot history/{slug}.yml, for example history/hagi-code-website.yml:

url: https://hagicode.com
status: up
code: 200
responseTime: 96
lastUpdated: 2026-06-17T00:22:34.485Z
startTime: 2026-03-24T10:07:32.531Z

shields.io endpoint badge data sources api/{slug}/response-time.json, uptime.json:

{"schemaVersion":1,"label":"response time","message":"739 ms","color":"yellow"}

And response time curve graphs graphs/{slug}/response-time-{day,week,month,year}.png.

The trade-off of this "files as database" approach is well-considered: write-heavy, read-light, controllable scale (about 288 samples per day per site, storing increments rather than full logs), naturally versioned, zero infrastructure. The cost, of course, is that the repository grows continuously and you occasionally need to look back and care about it.

Events and Notifications: Issues as Event Log

Incident logging relies on GitHub Issues, paired with two built-in repository templates: .github/ISSUE_TEMPLATE/bug_report.md (user-reported issues) and maintainance-event.md (scheduled maintenance). The maintenance template uses frontmatter to express the time window:

<!--
start: 2021-08-24T13:00:00.220Z
end: 2021-08-24T14:00:00.220Z
expectedDown: google, hacker-news
-->

Upptime parses these Issues and renders "maintenance in progress" and "past events" to the status page and README. Notifications rely on Issues' own watch mechanism, plus configurable webhooks, Slack, Telegram (declare notifications at the top of .upptimerc.yml; HagiCode's example repo currently doesn't have this enabled—after all, one less thing is one less thing).

Solution: Five Steps to Replicate a Status Page

Replicating a HagiCode-style status page, from zero to live, takes five steps total. Five steps sounds like a lot, but each one is short—take your time.

Step 1: Create Repository from Template

Don't git clone and modify—use GitHub's "Use this template" to create a repository directly (e.g., your-org/upptime). The template already includes all workflows, Issue templates, and the static site skeleton. After cloning locally, the only thing you need to manually modify is .upptimerc.yml—leave everything else alone.

Step 2: Edit `.upptimerc.yml`

Change owner/repo to yours, list the addresses you want to monitor in sites, configure status-website for the site. The minimum viable version looks roughly like this:

owner: your-org
repo: upptime

sites:
  - name: Main Site
    url: https://example.com
  - name: API Health
    url: https://api.example.com/health
    expectedStatusCodes:
      - 200

status-website:
  cname: status.example.com   # delete if no domain, use default your-org.github.io/upptime
  name: Example Status
  introTitle: "**Example Status**"
  introMessage: 服务可用性实时监控
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

Advanced items: expectedStatusCodes limits acceptable status codes (default 200-399); headers customizes request headers (for endpoints requiring auth); maxResponseTime marks slow responses. Use these as needed—take what you need.

Step 3: Configure Secrets and Permissions

The workflow defaults to ${{ secrets.GH_PAT || github.token }}. github.token can run the basic flow, but two limitations will bite you:

Workflows triggered by the default token won't trigger downstream workflows (to prevent loops), breaking the "probe → create Issue → notify" chain in the middle.
Insufficient permissions for cross-repo operations (like multi-org).

Recommend creating a new PAT (requires repo + workflow permissions) and storing it as repository Secret GH_PAT. update-template.yml has a specific check: without GH_PAT, it skips template auto-update and prints a warning, so this secret isn't just optional—it's key to peace of mind.

Step 4: Enable GitHub Pages

Repository Settings → Pages → Source select Deploy from a branch, branch select gh-pages, directory /root. site.yml automatically pushes build artifacts to this branch every day at 1 AM. If you configured cname, add a CNAME record at your DNS provider pointing to your-org.github.io.

It's also good to manually trigger once the first time: Actions page find "Static Site CI" → Run workflow, no need to wait foolishly for scheduled tasks—seeing results one second earlier means peace of mind one second earlier.

Step 5: Verification and Maintenance

After pushing the config, go to Actions and check if "Uptime CI" runs every 5 minutes and if history/ starts showing *.yml files. The status page address is https://<your-org>.github.io/upptime/ or your custom domain. Later, adding sites or changing domains only requires touching .upptimerc.yml one file—workflows are fully automated. HagiCode has maintained availability for 14 endpoints using this mechanism for over a year now, basically worry-free.

Practice: I've Walked Through the Potholes for You

The following items are experience accumulated from HagiCode's actual operation—written down so you can take fewer detours.

Practice 1: Monitoring Granularity Selection

HagiCode puts web pages (https://hagicode.com) and pure data endpoints (https://index.hagicode.com/server/index.json) in the same sites list. For JSON endpoints, Upptime makes requests and parses HTTP status codes but doesn't validate content structure. If you need deep checks like "returns 200 but content is wrong," you'll need to supplement with expectedStatusCodes plus external probes—Upptime itself only does black-box HTTP checks—it reads the face, not the mind.

Practice 2: Clever Use of Response Time Badges

api/{slug}/response-time.json is a shields.io endpoint badge data source. HagiCode's README heavily references these URLs:

https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FHagiCode-org%2Fupptime%2FHEAD%2Fapi%2Fhagi-code-website%2Fresponse-time.json

This way, you can embed real-time response time badges in any Markdown (project README, blog, third-party pages), with colors driven by the values in message and the color field. Note that using HEAD rather than master/main to reference raw files avoids widespread failures after branch renames—details hide stability.

Practice 3: Repository Size Control

Sampling every 5 minutes, history/ accumulates considerable volume over a year. Upptime uses incremental YAML rather than full logs, which is relatively restrained, but it's still recommended to occasionally check repository size. If a site's monitoring value declines, remove it from sites—corresponding historical files can also be manually cleaned up; after all, if you can't bear to delete, the repository will eventually show you what bloating means.

Practice 4: Real Usage of Maintenance Events

maintainance-event.md isn't decoration. Before a planned release, create an Issue using the template, fill in start/end/expectedDown, and Upptime will mark corresponding sites during that period as "scheduled maintenance," not counting them toward availability statistics, avoiding dragging down the full-year SLA with a normal release. HagiCode's expectedDown supports comma-separated site name lists, corresponding one-to-one with sites[].name.

Practice 5: Boundaries Between Template Updates and Customization

The Do not edit this file directly! at the top of all .github/workflows/*.yml isn't meant to scare you. update-template.yml overwrites these files with the upstream template weekly. When you need custom behavior, the correct approach is to use officially supported config items in .upptimerc.yml (like skipTopics, customStatusWebsite, runnerSettings), not to modify workflows. If you really must modify workflows, either turn off update-template.yml or fork and maintain the template yourself—the latter loses painless upgrades; weigh the trade-offs yourself.

Practice 6: Reality Constraints of Free Quotas

GitHub Actions is free and unlimited for public repositories, which Upptime's design exploits. Private repositories have 2000 free minutes per month, while uptime.yml runs every 5 minutes for about 1 minute each time—just this one item costs about 8640 minutes per month, exceeding the quota. So the Upptime repository must be public—this is the premise of "free"—don't go private for secrecy and then receive a bill, that's awkward.

Conclusion

Returning to the initial question: monitoring a pile of external services—is there really a cheap solution? HagiCode's answer is—yes, and so cheap you'll doubt it's real. Upptime breaks monitoring into four GitHub native components:

Probes = GitHub Actions cron
Database = YAML/JSON files in the repository
CDN = GitHub Pages
Event log = GitHub Issues

You get: real-time availability, response time curves, historical events, availability badges, custom domains, automatic notifications—all with zero servers and zero monthly fees. The cost is keeping the repository public and occasionally caring about repository size. Compared to hand-rolling a monitoring solution, this cost is actually far lighter.

The reason this solution works is behind GitHub's ecosystem's sincere subsidy for open-source projects. If you're also maintaining a small multi-site product matrix, I strongly recommend spending an afternoon setting this up—it's far less worry than hand-rolling monitoring.

References

Summary

Around "How to use Upptime to build your own status page for free," a more prudent approach is to gradually get key configurations, dependency boundaries, and landing paths working first, then fill in optimization details.

Once goals, steps, and acceptance criteria are clear, such solutions can typically enter actual delivery more smoothly.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-18-how-to-use-upptime-for-free-status-page%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission

Hagicode — Thu, 18 Jun 2026 02:58:33 +0000

How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission

At its core, Electron is just an ordinary Win32 desktop application, but the Microsoft Store only recognizes MSIX. This article, drawing from the actual build configuration we used for HagiCode Desktop, breaks down the entire chain from "registering a developer account → creating MSIX packages → submitting to the store" from start to finish. We'll also discuss the pitfalls we encountered along the way—after all, once you've fallen into the traps, they become stories.

Background

You have an Electron application that needs to be distributed to end users on Windows. Beyond the NSIS installer packages and portable versions we've always used, we also wanted it available in the Microsoft Store. The reasons are actually quite practical:

Trusted Distribution Channel: Apps in the store are signed and reviewed, so users won't be blocked by SmartScreen during installation, and they won't have to face that cold "Unknown publisher" warning.
Automatic Updates and Commercialization: The store handles updates for you; subscriptions and permanent licenses can be directly integrated.
Coverage of Built-in Windows 10/11 Entry Points: winget, store search, Start menu recommendations—these entry points are genuinely useful for user acquisition.

However, Electron is ultimately not UWP. To publish to the Microsoft Store, the core task is essentially one thing—repackage Electron's output into an MSIX package that the Microsoft Store recognizes, and then complete the registration and submission process dutifully. It sounds simple, but once you actually get started, there are quite a few pitfalls. We spent significant effort mapping out the entire process to fill in these gaps. Below, we'll break down each step in detail.

About HagiCode

The solution described in this article comes from our practice in the HagiCode project. HagiCode Desktop is an Electron-based desktop application that needs to be distributed to users through three channels: the official website, GitHub Release, and the Microsoft Store. This article explains how we connected the store channel. There's more information about HagiCode at the end—if you're interested, feel free to scroll down.

Analysis: Four Critical Questions to Clarify Before Publishing

Publishing to the Microsoft Store involves four key technical judgments. Once you've thought these through clearly, you won't need to repeatedly backtrack later—after all, no one wants to redo their work.

1. Microsoft Store Only Accepts MSIX / AppX, Not Traditional NSIS/EXE

The Microsoft Store's support for desktop applications (Desktop Bridge) is built on the MSIX format. Traditional NSIS installer packages cannot be submitted directly; they must first be repackaged into MSIX using MakeAppx. Fortunately, Electron Forge provides a @electron-forge/maker-msix maker that can produce MSIX directly during the packaging phase, saving you the hassle of reverse-engineering packaging from an installed directory.

Our project includes this maker:

{
  name: '@electron-forge/maker-msix',
  platforms: ['win32'],
  config: {
    appManifest: msixManifestPath,
    packageAssets: msixAssetsPath,
    logLevel: 'warn',
    ...(windowsKitPath ? { windowsKitPath } : {}),
    ...(windowsKitVersion ? { windowsKitVersion } : {}),
    ...msixSigningConfig,
  },
},

The key inputs are essentially two: appManifest (AppxManifest.xml, which defines package identity and capabilities) and packageAssets (store icon assets). If either of these is wrong, everything else, no matter how well done, is wasted effort.

2. Package Identity Must Be Reserved in Partner Center in Advance

The Identity field (Name, Publisher) in the MSIX package cannot be filled in arbitrarily—it must match exactly the application identity reserved in Partner Center. Even one character off will result in rejection. Our reserved identity is stored in forge.store-config.json:

{
  "packageIdentity": {
    "displayName": "Hagicode",
    "publisherDisplayName": "newbe36524",
    "publisher": "CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F",
    "identityName": "newbe36524.Hagicode",
    "backgroundColor": "transparent",
    "languages": ["en-US", "zh-CN", "zh-TW", "ja-JP", "ko-KR", "de-DE", "fr-FR", "es-ES", "pt-BR", "ru-RU"]
  }
}

That publisher string comes from the certificate subject issued by Microsoft after developer account registration and must match character-for-character. The identityName is the package name prefix you reserved. This string must be copied exactly from Partner Center—never type it manually. We'll discuss this again in the "Common Pitfalls" section later.

3. Desktop Applications Must Declare `runFullTrust` Capability

Electron applications need full file system access, need to spawn child processes, and need to run the Node runtime—these can only be achieved in "full trust" mode. Therefore, the MSIX manifest must honestly declare the runFullTrust capability, otherwise the application will be blocked by the sandbox upon startup, manifesting as various baffling crashes. Our configuration looks like this:

{
  "msix": {
    "minVersion": "10.0.17763.0",
    "maxVersionTested": "10.0.19045.0",
    "capabilities": [
      "runFullTrust",
      "internetClient",
      "internetClientServer",
      "privateNetworkClientsServer"
    ]
  }
}

runFullTrust is the standard for desktop application publishing. Setting minVersion to 17763 (Windows 10 1809) is because from this version onwards, MSIX has stable support for desktop Win32 applications; set it lower and users can't install it; set it higher and you won't cover those older machines.

4. Store Submission Requires Windows Environment + Microsoft Store CLI

Packaging can be done on cross-platform CI, but store submission (msstore publish) cannot—it must run the Microsoft Store CLI in a Windows environment with Azure AD application credentials configured. This is why the publish_store job in the automation pipeline must run on a windows-latest runner. This is a hard constraint that can't be bypassed, unlike packaging which can be stuffed into a Linux container.

Solution: Eight-Step Process for Complete Store Publishing

Connecting the analysis above, the complete steps to publish an Electron app to the Microsoft Store are roughly as follows.

Step 1: Register a Developer Account

First, go to Partner Center to register a developer account (individual or company) and pay the one-time fee. After the account is activated, you'll receive a Publisher certificate subject string, which looks roughly like this: CN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. This is the only source for the publisher field later.

Step 2: Reserve Application Identity in the Store

Create a new application in Partner Center and fill in the name you want to reserve. The system will assign you an identityName, which combined with your own Publisher forms the complete package identity. Copy this identity exactly into your local configuration:

// forge.store-config.json
{
  "packageIdentity": {
    "displayName": "Hagicode",
    "publisherDisplayName": "newbe36524",
    "publisher": "CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F",
    "identityName": "newbe36524.Hagicode"
  }
}

Step 3: Prepare Store Icon Assets

The Microsoft Store requires a set of PNGs in fixed dimensions: StoreLogo.png, Square44x44Logo.png, Square150x150Logo.png, Wide310x150Logo.png, etc. Our prepare-msix.js script validates whether all these assets are present before packaging:

// Validate required store icon assets, missing even one won't work
const requiredAssets = ['StoreLogo.png', 'Square44x44Logo.png', 'Square150x150Logo.png', 'Wide310x150Logo.png'];
for (const assetName of requiredAssets) {
  const assetPath = path.join(paths.generatedAssetsPath, assetName);
  if (!fs.existsSync(assetPath)) {
    throw new Error(`Missing required MSIX asset after preparation: ${assetPath}`);
  }
}

Why do this? Because if one size is missing, MakeAppx won't tell you exactly what's wrong during packaging, and you'll only get rejected during store review—by which time you've already waited several days. Validating in advance is an effective defense.

Step 4: Generate AppxManifest.xml

The manifest needs to include package identity, capabilities, visual assets, and the entry executable. We use an override configuration (forge.store-config.json) to drive prepare-msix.js to generate the manifest, ensuring the identity matches the store. The key sections of the manifest look roughly like this:

<!-- Package identity: must match Partner Center -->
<Identity Name="newbe36524.Hagicode"
          Publisher="CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F"
          Version="1.2.3.0" />

<Applications>
  <Application Id="Hagicode" Executable="Hagicode.exe" EntryPoint="Windows.FullTrustApplication">
    <uap:VisualElements ... />
  </Application>
</Applications>

<!-- Capability declaration: runFullTrust is key for desktop apps -->
<Capabilities>
  <rescap:Capability Name="runFullTrust" />
  <Capability Name="internetClientServer" />
</Capabilities>

Note that line EntryPoint="Windows.FullTrustApplication"—this is a critical marker for desktop applications. Combined with the runFullTrust capability, it allows the app to run with full permissions. Without it, the app is confined to the sandbox, quite frustratingly.

Step 5: Package with maker-msix

The build command is in package.json:

{
  "scripts": {
    "build:win:store": "npm run generate:store-bindings && node scripts/build-store-package.js"
  }
}

It ultimately calls Electron Forge, passing forge.store-config.json as an override configuration. The maker-msix will call the Windows SDK's MakeAppx to output an .msix file. There's a hard constraint here: packaging must be done on Windows (or in a container with Windows SDK), since it depends on MakeAppx—this can't be bypassed.

Step 6: Sign (Can Skip for Store Submission)

This step is easily overlooked—packages submitted to the store are re-signed by Microsoft with their own certificates, so for development self-testing outside "formal submission," you don't need to sign. However, if you want to install and test locally, you need to sign with a trusted certificate, otherwise Windows will refuse installation. Our resolveMsixSigningConfig returns an empty object when no signing materials are configured, letting the process continue:

// Don't sign if no signing materials configured, let the store re-sign uniformly
function resolveMsixSigningConfig() {
  if (!process.env.MSIX_CERT_FILE) return {};
  return {
    signMethod: 'signtool',
    certFilePath: process.env.MSIX_CERT_FILE,
    certPassword: process.env.MSIX_CERT_PASSWORD,
  };
}

Separating the "self-testing signing" and "submitting unsigned" paths is a key practice.

Step 7: Configure Microsoft Store CLI Credentials

Create an Azure AD application in the Azure portal, grant it permissions to access Partner Center, and obtain the following set of credentials:

AZURE_AD_APPLICATION_CLIENT_ID
AZURE_AD_APPLICATION_SECRET
AZURE_AD_TENANT_ID
SELLER_ID (Seller ID from Partner Center)
MICROSOFT_STORE_PRODUCT_ID (Product ID of the reserved application)

This step is slightly convoluted, but the documentation for both Azure Portal and Partner Center is quite detailed—just follow it.

Step 8: Submit to Store

In a Windows environment, submit using the Microsoft Store CLI:

# Configure credentials
msstore reconfigure --tenantId $env:AZURE_AD_TENANT_ID `
  --clientId $env:AZURE_AD_APPLICATION_CLIENT_ID `
  --clientSecret $env:AZURE_AD_APPLICATION_SECRET `
  --sellerId $env:SELLER_ID

# Submit MSIX package to the reserved product
msstore publish "$packagePath" -id $env:MICROSOFT_STORE_PRODUCT_ID

After submission, you need to return to Partner Center to fill in the store listing details (description, screenshots, pricing, rating), then click submit for review. Review typically takes 1–3 business days; first submissions tend to take longer.

Practice: Consolidating Configuration and Pitfall Experience

After going through the process once, these practices can help you avoid some detours—after all, after you've taken enough detours, they don't feel like detours anymore, but some things can still be skipped.

Store Configuration Files Separately

Separating "general build configuration" from "store-specific configuration" is key. Our approach is: forge.config.js handles daily builds (NSIS, portable, macOS dmg), while forge.store-config.json only extends and overrides during store builds:

{
  "extends": "forge.config.js",
  "buildVersion": "0.1.0.0",
  "packageIdentity": { /* store reserved identity */ },
  "msix": {
    "minVersion": "10.0.17763.0",
    "maxVersionTested": "10.0.19045.0",
    "capabilities": ["runFullTrust", "internetClient", "internetClientServer", "privateNetworkClientsServer"]
  }
}

This way, store builds and release builds don't pollute each other. HagiCode Desktop maintains three distribution channels simultaneously; configuration separation is the prerequisite for our stable iteration.

Version Numbers Must Be Four Segments

MSIX version numbers must be four segments (Major.Minor.Build.Revision, e.g., 1.2.3.0), but Electron's package.json typically only has three segments. That buildVersion field is used to fill in the last segment—when submitting to the store, version numbers must increment, and the fourth segment is very convenient for distinguishing multiple submissions under the same semantic version. Those who've encountered this will understand; those who haven't will eventually.

Multi-Language Declaration

The store supports multi-language listings, which in the manifest corresponds to each <Resource Language="..." /> tag. We declared ten languages, and the store requires filling in a description for each (you can use machine translation to pass review first, then localize gradually). The corresponding rendering logic in prepare-msix.js is:

// Render language list as Resource tags in MSIX manifest
function renderResourceTags(languages) {
  return languages
    .map((language) => `    <Resource Language="${escapeXml(language)}" />`)
    .join('\n');
}

Common Pitfalls (Focus Here)

HagiCode Desktop has encountered almost every one of these pitfalls:

Publisher Mismatch: When copying the publisher string from Partner Center, it's easy to accidentally lose a space or mess up the case, leading to immediate rejection.建议直接写成配置文件，别手敲。
Missing runFullTrust: After the app starts, it can't access the file system or spawn child processes, manifesting as various bizarre crashes that are frustrating to debug.
Incomplete Icon Sizes: MakeAppx doesn't validate, but store review will reject it. prepare-msix.js validating in advance is an effective defense.
Non-Incrementing Version Numbers: The store refuses to accept the same or lower version numbers; CI pipelines must ensure bumping on each build.
Running maker-msix in Non-Windows Environments: It won't find MakeAppx; you must use a windows-latest runner.
Signing Confusion: Use self-signed certificates for self-testing, submit unsigned for store submission and let Microsoft re-sign—separate these two paths, don't stuff self-signed certificates into submission packages.

Automation Recommendations

After manually going through the entire process once and understanding each step, it's strongly recommended to connect GitHub Actions for automation. We eventually chained version parsing, MSIX building, GitHub Release publishing, and store publishing into a pipeline, checking for new versions every 4 hours. These details are fully broken down in our other article "Automating Windows App Publication to Microsoft Store."

If you just want to get your app on the store first and integrate commercialization (subscriptions / permanent licenses) later, you can also check out our "How to Integrate Microsoft Store Subscriptions and Permanent Licenses in Electron Desktop Apps"—that article covers connecting commercialization capabilities after store publication.

References

Summary

Regarding "How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission," a more prudent approach is to first run through key configurations, dependency boundaries, and implementation paths step by step, then fill in optimization details.

Once objectives, steps, and acceptance criteria are clear, such solutions can typically enter actual delivery more smoothly.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-18-electron-app-publish-to-microsoft-store%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How to Call Windows Native APIs in Electron

Hagicode — Wed, 17 Jun 2026 03:22:36 +0000

How to Call Windows Native APIs in Electron

Calling Windows native APIs in an Electron app feels like wanting to see the ocean but only having a map. After some trial and error, I've found a few paths—writing this article serves as a record and a guide for others who might follow.

Background

When building Electron desktop applications, you inevitably need to interact with the operating system. On Windows, these requirements are quite common:

Calling Windows Store APIs for in-app purchases
Handling file system virtualization specific to Windows Store apps
Obtaining system-level permissions and resources
Interacting with Windows Runtime (WinRT) components

Electron is fundamentally a Node.js environment, and Node.js doesn't natively provide direct access to Windows native APIs. A bridge is needed between the two.

It's like trying to communicate with a friend who doesn't speak Chinese—you need a translator. Electron is written in JavaScript, Windows APIs in C/C++. The language barrier requires building a bridge. That's the harsh reality of the code world.

About HagiCode

The solutions shared in this article come from our practical experience with the HagiCode project. HagiCode Desktop needs to call Microsoft Store APIs to handle subscription purchases and license management, which is why we developed a set of technical solutions. After all, necessity drives innovation—that's a truth.

Technical Solution Comparison

When calling Windows native APIs in Electron, there are several mainstream approaches to choose from. Each has its applicable scenarios—like different tools in a toolbox, they work best when used in the right place, otherwise just add trouble.

Solution	Applicable Scenarios	Pros	Cons
dynwinrt	WinRT APIs (e.g., Store API)	Type-safe, auto-generated bindings, modern JavaScript support	Only supports WinRT APIs, requires Windows SDK
Native Node.js Extensions	High performance, any Windows API	Complete control, optimal performance	Requires C++ development skills, complex cross-platform compatibility
child_process + PowerShell	Temporary, one-off calls	Simple and fast, no compilation needed	Poor performance, complex error handling
edge.js/ffi-napi	Calling existing DLLs	Can reuse existing libraries	Compatibility issues, high maintenance cost

HagiCode Desktop adopts a hybrid approach: using dynwinrt to access Windows Store APIs, native Node.js extensions for high-performance Store purchase operations, and Node.js's native fs and path modules to handle Windows Store app-specific file system virtualization. Keep it simple when possible—that's our principle.

Solution 1: Using dynwinrt to Call WinRT APIs

dynwinrt is a toolchain provided by Microsoft that can automatically generate JavaScript bindings based on Windows SDK metadata files. It's specifically designed for calling WinRT APIs, like Windows Store APIs.

Install dependencies:

{
  "optionalDependencies": {
    "@microsoft/dynwinrt": "0.1.0-preview.6",
    "@microsoft/dynwinrt-codegen": "0.1.0-preview.6"
  }
}

Generate WinRT bindings:

// scripts/generate-store-bindings.js
const { execFileSync } = 'node:child_process';

function generateStoreNamespace(windowsWinmdPath) {
  execFileSync('npx', [
    'dynwinrt-codegen',
    'generate',
    '--winmd', windowsWinmdPath,
    '--namespace', 'Windows.Services.Store',
    '--output', 'src/main/subscription/generated-js',
    '--lang', 'js',
  ]);
}

Use generated bindings:

// Using Store API bindings generated by dynwinrt
import { Windows } from '../subscription/generated-js/index.js';

async function queryStoreProduct(storeId: string) {
  const storeContext = Windows.Services.Store.StoreContext.getDefault();
  const result = await storeContext.getAssociatedStoreProductsAsync(['Subscription', 'Durable']);

  if (result.extendedError !== 0) {
    throw new Error(`Store API error: ${result.extendedError}`);
  }

  return result.products.get(storeId);
}

dynwinrt's advantage is type safety, and the generated code aligns with modern JavaScript conventions. But it can only handle WinRT APIs—if you need to call traditional Win32 APIs, you'll need other solutions. That's how tools work—each has its strengths.

Solution 2: Native Node.js Extensions

When high performance is needed or dynwinrt doesn't support the functionality, native Node.js extensions are the best choice. This approach requires writing C++ code, then compiling it into .node files using node-gyp.

Create binding.gyp:

{
  "targets": [{
    "target_name": "windows-store-addon",
    "sources": ["src/windows-store-addon.cpp"],
    "include_dirs": [
      "<!(node -e \"require('nan')\")"
    ],
    "defines": [
      "WIN32_LEAN_AND_MEAN"
    ]
  }]
}

C++ native module example:

// src/windows-store-addon.cpp
#include <nan.h>
#include <windows.h>
#include <wrl.h>
#include <windows.services.store.h>

using namespace v8;
using namespace Windows::Services::Store;

NAN_METHOD(QueryStoreStatus) {
  auto async = new Nan::AsyncWorker(
    []() {
      // Call Windows Store API
      auto context = StoreContext::GetDefault();
      auto products = context->GetAssociatedStoreProductsAsync(...)->GetResults();
      // Process results
    }
  );
  Nan::AsyncQueueWorker(async);
}

NAN_MODULE_INIT(InitModule) {
  Nan::Set(target, Nan::New("queryStoreStatus").ToLocalChecked(),
           Nan::GetFunction(Nan::New<FunctionTemplate>(QueryStoreStatus)).ToLocalChecked());
}

NODE_MODULE(windows_store_addon, InitModule)

Compile and use:

node-gyp rebuild

import addon from './build/Release/windows-store-addon.node';

const result = addon.queryStoreStatus({
  storeId: 'your-store-id',
  productKinds: ['Subscription', 'Durable']
});

Native extensions offer the best performance, but development costs are high. You need C++ skills and must handle cross-platform compatibility issues. If your team has C++ experience or performance requirements are particularly demanding, this solution is worth the investment. But this path is ultimately more challenging.

Solution 3: Handling Windows Store App Virtualization

Windows Store apps run in a virtualized environment, requiring special path mapping. HagiCode Desktop uses the following function to handle this:

// src/main/windows-store-path-display.ts
export function resolveWindowsStorePackageFamilyName(executablePath: string): string | null {
  const WINDOWS_APPS_SEGMENT = '\\windowsapps\\';
  const windowsPath = executablePath.replace(/\//g, '\\');
  const markerIndex = windowsPath.toLowerCase().indexOf(WINDOWS_APPS_SEGMENT);

  if (markerIndex < 0) return null;

  const relativePath = windowsPath.slice(markerIndex + WINDOWS_APPS_SEGMENT.length);
  const packageFullName = relativePath.split('\\', 1)[0]?.trim();
  return packageFullName || null;
}

export function resolveWindowsStoreVirtualizedPhysicalPath(
  logicalPath: string,
  options: ResolveWindowsStorePathDisplayOptions = {}
): string | null {
  const packageFamilyName = options.packageFamilyName
    ?? resolveWindowsStorePackageFamilyName(options.execPath ?? process.execPath);
  if (!packageFamilyName) return null;

  const packageStorageRoot = path.win32.join(
    options.env.LOCALAPPDATA,
    'Packages',
    packageFamilyName
  );

  // Map virtualized path to physical path
  if (isPathWithinWindowsRoot(logicalPath, options.env.APPDATA)) {
    return path.win32.join(
      packageStorageRoot,
      'LocalCache',
      'Roaming',
      path.win32.relative(options.env.APPDATA, logicalPath)
    );
  }

  return null;
}

Virtualization is quite complex. Simply put, the file paths that Windows Store apps see differ from actual storage locations, requiring translation. The code above performs this translation. Like memory and reality, sometimes they don't align and require patience to distinguish.

Practical Experience

Platform Detection

Always check process.platform === 'win32' to avoid executing Windows-specific code on non-Windows platforms. This is a good habit—like checking the weather before leaving home to avoid getting caught in the rain.

if (process.platform !== 'win32') {
  return { availability: 'not-supported' };
}

Error Handling

Windows API calls may fail and need proper error handling. We've learned this the hard way—without comprehensive error handling, users have no idea what went wrong when problems occur. Actually, writing more code teaches you that error handling isn't for anyone else—it's just to save yourself trouble.

function normalizeThrownError(error: unknown): { errorCode: string | null; errorMessage: string | null } {
  if (error instanceof Error) {
    const errorWithCode = error as Error & { code?: unknown };
    return {
      errorCode: normalizeErrorCode(errorWithCode.code) ?? error.name,
      errorMessage: error.message,
    };
  }
  return { errorCode: null, errorMessage: error == null ? null : String(error) };
}

Async Handling

Most Windows Store APIs are asynchronous—use Promise or async/await. When writing async code, remember to handle edge cases like timeouts and cancellation. The taste of waiting—no one wants more of that.

async function queryStatus(): Promise<RawStoreLicenseState> {
  try {
    const result = await storeContext.getAssociatedStoreProductsAsync(productKinds);
    return buildSupportedStateFromProductQueries(result);
  } catch (error) {
    return buildUnavailableState(error);
  }
}

Resource Cleanup

Ensure native resources are released when no longer needed. C++ resources aren't automatically collected—manual release is a good habit. Like some things, you can only travel light after letting them go.

class MicrosoftStoreSubscriptionBroker {
  private broker: StoreLicensePlatformBroker | null = null;

  dispose(): void {
    this.broker?.dispose();
    this.broker = null;
  }
}

Timestamp Conversion

Windows uses 1601-01-01 as its epoch, which needs conversion to Unix timestamps. This detail is easily overlooked, but if handled incorrectly, dates will be completely wrong. Time—a small difference makes a big difference.

const WINDOWS_EPOCH_OFFSET_MILLISECONDS = 11644473600000n;
const HUNDRED_NANOSECONDS_PER_MILLISECOND = 10000n;

function toIsoDate(value: unknown): string | null {
  const universalTime = (value as { universalTime?: unknown } | null)?.universalTime;
  const ticks = typeof universalTime === 'bigint' ? universalTime : null;

  if (ticks == null) return null;

  const unixMilliseconds = ticks / HUNDRED_NANOSECONDS_PER_MILLISECOND - WINDOWS_EPOCH_OFFSET_MILLISECONDS;
  return new Date(Number(unixMilliseconds)).toISOString();
}

Best Practices

Based on our experience with the HagiCode project, here are a few recommendations:

Prioritize dynwinrt: For WinRT APIs, dynwinrt provides type-safe and modern JavaScript bindings
Minimize native extensions: Only use native extensions when truly necessary for high performance or unsupported features
Cross-platform compatibility: Use conditional compilation or runtime detection for different platforms
Test coverage: Thoroughly test native API calls on Windows, including error scenarios
Documentation: Clearly document the purpose and potential side effects of each native API call

When writing code, keep it simple if possible. If dynwinrt can solve the problem, don't write C++ extensions. Maintenance costs will be much lower. This is a small insight—not some profound truth.

Summary

Calling Windows native APIs is an important means for Electron apps to implement advanced features on Windows. This article shares several technical solutions used in the HagiCode Desktop project: dynwinrt for WinRT APIs, native Node.js extensions for high-performance scenarios, and virtualized path handling for Store app file access.

Which solution to choose depends on your specific needs. If you're only calling WinRT APIs, dynwinrt is the simplest choice. If you need high performance or traditional Win32 APIs, native extensions are essential. For temporary operations, using child_process to call PowerShell works too. All roads lead to Rome—some are easier to travel, others a bit more winding.

Regardless of which solution you use, remember these principles: proper platform detection, comprehensive error handling, careful async handling, timely resource cleanup. These details determine the robustness of your code. Writing code for long enough teaches you that details matter more than grand frameworks.

If you're working on similar development, I hope these experiences help you. Technology—you gain experience after stumbling enough. Like life—you learn to walk after falling enough...

References

Summary

A more steady approach to "How to Call Windows Native APIs in Electron" is to first validate key configurations, dependency boundaries, and implementation paths, then fill in optimization details.

Once objectives, steps, and acceptance criteria are clear, such solutions typically enter actual delivery more smoothly.

Integrating Microsoft Store Subscription and Permanent Licenses in Electron Desktop Apps

Hagicode — Tue, 16 Jun 2026 12:26:16 +0000

Integrating Microsoft Store Subscription and Permanent Licenses in Electron Desktop Apps

When your Electron app needs to sell subscriptions and perpetual licenses through Microsoft Store, how do you cleanly integrate that WinRT commercial API into your business logic? This is an old story—we stumbled and sweated through it in HagiCode Desktop, eventually figuring out this layered approach. Writing it down as a roadmap for those who come after.

Background

HagiCode Desktop is an Electron application distributed through Microsoft Store. Commercially, there are only two product types: one is the Sponsor Plan (sponsor subscription, Store ID 9N0BTGWV23M1), renewing monthly or annually—like a relationship that needs constant watering. The other is TurboEngine (perpetual license DLC, Store ID 9NSD809W18Z6), a one-time purchase—like that old book on the shelf you never opened again, but it's yours nonetheless.

The problem is, the Electron runtime itself doesn't have the ability to directly call Microsoft Store commercial APIs. Store purchases and license queries all rely on WinRT's Windows.Services.Store namespace, and these APIs can only be used in native code. But the Electron main process is in a Node.js environment—you can't import a WinRT type there—it's like trying to hold moonlight in your hand, but coming up empty.

Even more troublesome is that commercialization status isn't something you can just check once and feel at peace. Users might unsubscribe, renew, or switch devices in the Store client, and the app's feature toggles need to change accordingly. Making users click "refresh" every time makes for a poor experience, but querying too frequently hits Store rate limits—network jitters and a perfectly good subscription gets reported as "not subscribed," locking out paid users' features. Building something like that makes you want to laugh to hide the tears.

There's another easily overlooked corner: different distribution channels behave differently. Non-Store versions (like portable builds) don't have the Store runtime at all—calling StoreContext will fail outright. In such cases, the app shouldn't crash, nor should it pretend users have subscriptions. You need to give a clear "unsupported" status. After all, pretending to have something is sadder than honestly admitting you don't.

For these reasons, we built a layered architecture. This approach later crystallized into two HagiCode OpenSpec proposals: desktop-subscription-entitlements (subscription license persistence, standardization, and entitlement derivation) and desktop-turboengine-msstore-license (TurboEngine perpetual license purchase, refresh, and DLC injection). More on these below.

About HagiCode

The solution shared in this article comes from our practice in the HagiCode project. HagiCode is an AI coding assistant project spanning multiple platforms: Web, Desktop, CLI, and more. HagiCode Desktop is the desktop product line discussed in this article, and the complete source code is available at HagiCode-org/site.

Layering is Key

Writing Store calls directly in the Electron main process gets messy. WinRT async objects, COM threading models, window handle passing—mixing these with business logic makes the code nearly unmaintainable. Our approach is to slice the entire pipeline into four layers, each shouldering one responsibility:

Renderer Process (React)
   ↕  IPC bridge
Electron Main Process (TypeScript)
   ↕  broker interface
Native Node Addon (C++)
   ↕  WinRT
Windows.Services.Store

At the bottom is a C++ native addon named hagicode_store_purchase_addon.node. It exposes only two methods: requestPurchase(storeId, windowHandle) and queryStoreStatus(storeId, productName, productKinds). These correspond to WinRT's RequestPurchaseAsync and GetAssociatedStoreProductsAsync / GetUserCollectionAsync. The addon's entire job is to convert WinRT async results to JSON and send them back to the JavaScript thread via Napi::ThreadSafeFunction.

In the middle is a TypeScript StoreLicenseService. It doesn't care about WinRT, only about business semantics: refresh, retry, cache, entitlement derivation, and status broadcasting. It communicates with the underlying layer through a StoreLicensePlatformBroker interface with just three methods: queryStatus(), purchase(), and dispose().

At the top are SubscriptionService and TurboEngineLicenseService, which are essentially thin wrappers around StoreLicenseService, each bound to specific product configurations (Store ID, product name, entitlement names).

This layering brings a direct benefit: subscriptions and perpetual licenses can share the same engine. StoreLicenseService is a generic class parameterized by snapshot type and entitlement name. Adding a new product only requires writing another StoreLicenseProductConfig—no need to copy-paste the entire service. If HagiCode later needs to integrate macOS's StoreKit or other commercialization channels, theoretically only the broker implementation needs to change—no business layer code needs to move. This is the gentle power of layering.

Standardization: Cleaning Store's Dirty Data

The data returned by WinRT is quite "raw." StoreProductQueryResult contains nested IVectorView and IMap, SKU's CollectionData.EndDate is in Windows DateTime ticks (starting from 1601, in 100-nanosecond units), and error codes are HRESULTs. If you throw these directly at the renderer process, the frontend code will likely collapse.

So the broker layer does standardization, flattening the raw WinRT objects into RawStoreLicenseState:

export interface RawStoreLicenseState {
  fetchedAt: string;
  availability: 'supported' | 'store-unavailable' | 'error';
  appLicenseActive: boolean;
  product: RawStoreLicenseProduct | null;
  sku: RawStoreLicenseSku | null;
  license: RawStoreLicense | null;
  purchaseEligibility: 'licensable' | 'not-licensable' | 'license-action-not-applicable' | 'network-error' | 'server-error' | 'unknown';
  errorCode: string | null;
  errorMessage: string | null;
}

There's a detail worth mentioning: the query actually uses two Store calls. One is GetAssociatedStoreProductsAsync (products associated with the current app), the other is GetUserCollectionAsync (products the user already owns). The reason is simple: subscription products might appear in the association list but the user hasn't bought them yet, or they might already be in the user's collection. Only by cross-referencing the two results can you accurately determine "whether owned"—it's like looking at a person from two angles to avoid misjudgment.

The ticks-to-ISO date conversion is worth noting:

const WINDOWS_EPOCH_OFFSET_MILLISECONDS = 11644473600000n;
const HUNDRED_NANOSECONDS_PER_MILLISECOND = 10000n;

// ticks are in 100-nanosecond units from 1601; convert to milliseconds, then subtract the Windows/Unix epoch difference
const unixMilliseconds =
  ticks / HUNDRED_NANOSECONDS_PER_MILLISECOND - WINDOWS_EPOCH_OFFSET_MILLISECONDS;

11644473600000 is the number of milliseconds between 1601-01-01 and 1970-01-01. This conversion is also done in the C++ addon (using FileTimeToSystemTime), and both sides' results must match—otherwise you get bizarre misalignments like "main process sees today, addon sees yesterday." When time (like relationships) is misaligned, nothing makes sense.

State Machine: From "Raw Data" to "Business State"

After standardization, we need another layer of abstraction. Business code doesn't actually need to know what purchaseEligibility is—it only cares "is the subscription actually valid." The deriveStatus function in normalize.ts does this translation:

function deriveStatus(
  raw: RawStoreLicenseState,
  productConfig: StoreLicenseProductConfig
): StoreLicenseStatus {
  if (raw.availability !== 'supported') {
    return 'unknown';
  }

  const expirationDate =
    raw.license?.expirationDate ?? raw.sku?.collectionEndDate ?? null;
  const expirationTime = expirationDate ? Date.parse(expirationDate) : Number.NaN;
  const hasExpired = Number.isFinite(expirationTime) && expirationTime < Date.now();
  const isOwned = Boolean(
    raw.license?.isActive ||
      raw.sku?.isInUserCollection ||
      raw.product?.isInUserCollection
  );

  if (isOwned && !hasExpired) {
    return 'active';
  }
  if (hasExpired) {
    return 'expired';
  }
  // ...other branches: inactive / canceled / grace-period / pending
}

The final business states are seven: active, inactive, expired, canceled, grace-period, pending, unknown. The renderer process only looks at this one field, never touching the raw data again.

There's a design trade-off here: the active determination doesn't check whether expirationDate exists. The reason is simple—perpetual licenses (TurboEngine) don't have expiration dates at all; Store returning license.isActive as true is sufficient. If we insist "must have expiration date to be active," we'd incorrectly judge buyout users as unsubscribed—which would be too hurtful. This detail is explicitly stated in the spec: perpetual licenses remain active when no expiration metadata exists.

Fault Tolerance: Don't Lose Subscriptions When Network is Poor

Store APIs return errors or time out during network jitter. If we clear the state on every failure, paid users' permissions will frequently drop—this is obvious, but it does happen. HagiCode's strategy is "preserve last known good state on failure, mark as stale."

StoreLicenseService.refresh has an internal retry loop (default 3 times, 350ms interval) and does "status regression" detection: if the previous state was active but this query returns something not active, treat it as a temporary error and retry rather than accepting this degraded result directly.

private getRetryReason(
  snapshot: TSnapshot,
  recoverySnapshot: TSnapshot | null
): 'store-unavailable' | 'status-regression' | null {
  if (snapshot.availability !== 'supported') {
    return 'store-unavailable';
  }
  if (recoverySnapshot?.status === 'active' && snapshot.status !== 'active') {
    return 'status-regression';
  }
  return null;
}

Only after all retries fail will it use createStaleSnapshot to return the last good state marked as stale, accompanied by a store-refresh-failed diagnostic. The renderer process can decide whether to disable features in stale state—typically, continue allowing access, giving users a buffer. After all, no one wants to be unable to use something they paid for just because the network was bad that day.

Another detail is refreshInFlight deduplication. If a refresh is already in progress, new refresh calls reuse the same Promise, avoiding concurrent requests overwhelming the Store—the principle is the same as queuing:挤成一团反而谁也过不去。

Entitlement Derivation: Decoupling Status and Feature Toggles

Subscription status answers "is the subscription valid," but feature toggles care about "can the user use a specific feature." These aren't one-to-one correspondences. An active subscription might correspond to multiple entitlements (sponsor badge, premium feature gates), and future plans might include tier-based differentiation.

So we added an EntitlementEvaluator layer in between:

evaluate(snapshot: TSnapshot): TEntitlement[] {
  if (snapshot.availability !== 'supported' || snapshot.status !== 'active') {
    return [];
  }
  return [...this.activeEntitlements];
}

In the subscription product configuration, we declare which entitlements it grants when activated:

export const subscriptionEntitlementNames = [
  'sponsorBadge',
  'premiumFeatureGate',
] as const;

This way, feature code depends only on the entitlements array, not directly reading status. Future tier additions or entitlement splits only require changing configuration and the evaluator—consumer code doesn't need to change. This decoupling is especially important in multi-product-line projects like HagiCode—subscriptions and perpetual licenses share the same entitlement model, and the frontend only needs to query one array. The world suddenly feels much cleaner.

Runtime Degradation: What If No Store?

Calling the addon from non-Store distributed versions (portable builds, development environments) will fail. HagiCode uses lazy initialization and degradation in MicrosoftStoreSubscriptionBroker:

private async initializeBroker(): Promise<StoreLicensePlatformBroker> {
  try {
    return this.setBroker(
      await this.adapterFactory(this.windowHandle, this.productConfig)
    );
  } catch (error) {
    // If Store runtime isn't found, degrade to a "supports nothing" broker
    return this.setBroker(new UnavailableSubscriptionPlatformBroker(error));
  }
}

UnavailableSubscriptionPlatformBroker implements the same interface, but its queryStatus always returns store-unavailable, and purchase always returns not-supported. Upper-layer code is completely unaware—it just becomes "unsupported" status, and the renderer shows a "Please get through Microsoft Store" prompt based on that.

This design allows the entire commercialization module to run safely under any distribution channel without crashing due to missing Store runtime. If you're also building a multi-channel Electron app, this is particularly worth copying—don't let "environment not supported" become a crash. Some things, when admitted honestly, are actually more dignified.

Startup Flow and IPC Channels

On app startup, main.ts decides whether to initialize the subscription service based on the --desktop-subscription-enabled=1 parameter. This parameter is only included in the Store version's startup command, avoiding wasted loading in non-Store versions—every bit of effort saved is worth it.

function initializeSubscriptionService(): void {
  if (!subscriptionFeatureEnabled || subscriptionService) {
    return;
  }

  subscriptionService = new SubscriptionService({
    broker: new MicrosoftStoreSubscriptionBroker({
      windowHandle: mainWindow?.getNativeWindowHandle() ?? null,
    }),
    entitlementEvaluator: new EntitlementEvaluator(),
  });

  registerSubscriptionHandlers({
    subscriptionService,
    getWindows: () => ElectronBrowserWindow.getAllWindows(),
  });
}

windowHandle comes from mainWindow.getNativeWindowHandle(). This Buffer is parsed into a bigint and passed to the native addon, which then uses it to call IInitializeWithWindow::Initialize. This is a necessary step for Store API to pop up a purchase dialog in desktop apps (non-UWP); otherwise, the purchase window has no owner and behaves abnormally—a window without belonging is like a person without belonging: always drifting.

The renderer process calls the main process through the bridge exposed by preload:

const subscriptionBridge: SubscriptionBridge = {
  getSnapshot: (options) => ipcRenderer.invoke(subscriptionChannels.getSnapshot, options),
  verifyStartup: () => ipcRenderer.invoke(subscriptionChannels.verifyStartup),
  refresh: () => ipcRenderer.invoke(subscriptionChannels.refresh),
  purchase: () => ipcRenderer.invoke(subscriptionChannels.purchase),
  onDidChange: (callback) => {
    const listener = (_event, snapshot) => callback(snapshot);
    ipcRenderer.on(subscriptionChannels.changed, listener);
    return () => ipcRenderer.removeListener(subscriptionChannels.changed, listener);
  },
};

State changes are pushed to all windows via broadcastSnapshotChanged. After purchase completion, completePurchase triggers a refresh('purchase'), and the new state is automatically broadcast, updating the subscription UI in the renderer process in real time.

Additionally, main.ts has a setInterval silently syncing in the background (subscriptionService?.refresh('scheduled')). This allows the running app to catch renewals and unsubscribes users quietly make in the Store client. The frequency naturally can't be too high (Store has rate limits); the code uses minute-level intervals—not too far, not too close, just right.

Some Easy-to-Fall Pits

First, native addon thread safety. After WinRT async operations complete, the callback isn't on the JavaScript thread. Calling Napi APIs directly in the callback will crash. The addon uses Napi::ThreadSafeFunction::BlockingCall to deliver results back to the JS thread:

auto const status = threadsafeFunction_.BlockingCall(
    payload,
    [self](Napi::Env env, Napi::Function, PurchaseCompletion* data) {
        std::unique_ptr<PurchaseCompletion> ownedData{ data };
        self->ResolveOnJs(env, *ownedData);
    });

BlockingCall blocks the WinRT callback thread until the JS thread finishes processing. In this mode, the callback thread cannot be the JS thread itself, otherwise you get deadlock. Fortunately, WinRT's Completed callbacks typically run on STA or thread pools, which satisfies this condition.

Second, COM initialization. The Electron main thread might have already initialized COM. The addon wraps winrt::init_apartment in try-catch, ignoring failures:

try {
    winrt::init_apartment(winrt::apartment_type::single_threaded);
} catch (...) {
    // Electron might have already initialized COM for this thread; ignore
}

Without handling this, repeated initialization throws exceptions and addon loading fails. Some errors, when ignored, are actually correct.

Third, window handle precision. getNativeWindowHandle() returns a Buffer, which might be 4 bytes (32-bit) or 8 bytes (64-bit). It's then formatted as a hex string starting with 0x in the addon, and the C++ side parses it back to HWND using std::stoull. Why use strings instead of passing numbers directly? Because JavaScript's number precision is only 53 bits, and 64-bit pointers would lose precision. This pit is hard to discover without stepping in it—like some things, you can't explain them without experiencing them.

Fourth, state isolation. Subscription and perpetual license states must be stored separately. HagiCode's spec explicitly requires that TurboEngine's persistence not overwrite sponsor's state. The two snapshots are separated by different productKeys (subscription and turboengine), avoiding one product's refresh overwriting another's cache. When everyone minds their own business, the world is at peace.

Fifth, must refresh after purchase. After purchase completes, you must refresh once more to broadcast. completePurchase triggers refresh('purchase') for both succeeded and already-purchased cases, because Store's purchase result only tells you the transaction status, not the current license details. License status must be queried again—between promise and reality, there's always one confirmation.

Summary

This implementation has been running for a while and is relatively stable. What's most worth borrowing isn't any specific trick, but this layered approach: completely isolating "dealing with Store" in the broker and addon layers, with the upper layers handling only pure business semantics.

A few core experiences to remember:

Touch WinRT only in the C++ addon; the addon only does "async to JSON"—no business semantics.
Standardization and state machine are two layers; don't mix raw data and business state together.
On network failure, preserve the last good state and mark it stale—don't take away paid users' permissions.
Decouple entitlements and status; feature code only looks at the entitlements array.
Non-Store environments use a degraded broker—never let "unsupported" become a crash.

If you're also doing Store commercialization for Electron apps, I hope this layered approach helps you avoid a few pitfalls.

The solution shared in this article is what we actually stumbled through and optimized while developing HagiCode. If you think it has some value, it means our engineering skills are decent—which makes HagiCode itself worth a second look...

References

Summary

For "integrating Microsoft Store subscription and permanent licenses in Electron desktop apps," a more prudent approach is to first validate key configurations, dependency boundaries, and implementation paths, then fill in optimization details.

When goals, steps, and acceptance criteria are clear, such solutions usually proceed more smoothly into actual delivery.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-16-electron-msstore-subscription-license%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

From Scratch: How to Integrate Reasonix CLI into the HagiCode System

Hagicode — Tue, 09 Jun 2026 03:05:06 +0000

From Scratch: How to Integrate Reasonix CLI into the HagiCode System

This article shares the complete technical practice of integrating Reasonix CLI as a first-class Agent Provider into the HagiCode system, covering three-layer architecture design, key technical decisions, and frontend and backend implementation details.

Background

Reasonix CLI, as it happens, is a pretty interesting thing. It's an AI code assistant tool based on ACP (Agent Communication Protocol), providing powerful streaming and session management capabilities. Actually, in the HagiCode.Libs layer, we've already completed its underlying implementation. It's just that these components are still in an isolated state, like beautiful pearls that haven't been strung into a necklace. Users cannot use it through Hero profession selection, session execution paths, or monitoring panels, which is somewhat regrettable.

The problem we face is: how to elevate Reasonix to the same level as Codex, Hermes, and other first-class Agent Providers, implementing complete backend routing and frontend display? This isn't simply a matter of registering an enum value. It requires building a complete chain from low-level abstraction to user interface. It's like building a house—you can't just lay a foundation and call it done. You have to build the walls and put up the roof.

The challenge of this integration lies in the fact that Reasonix, as a local CLI tool, has its own personality and temperament. For example, it doesn't need a connection string—all parameters are configured by the user at runtime; it might not even be installed, requiring graceful degradation; it's compatible with anthropic series models, but also has its own ACP-specific parameters like effort, budget, and so on. It's like a person with their own unique way of handling things—you can't force it.

After careful architectural design and multiple rounds of discussion, we finally adopted a clear three-layer architecture solution, successfully integrating Reasonix into the system. This solution not only solved the immediate problem but also provided a reusable pattern for subsequent similar CLI Provider integrations. Actually, many things are like this—once you find the right method, the path forward becomes much easier.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an open-source AI code assistant project dedicated to providing developers with powerful code generation, refactoring, and optimization capabilities. During development, we encountered various technical challenges, and integrating Reasonix as a first-class Agent Provider was one of them. If you find the solution shared in this article valuable, it means our engineering practice isn't bad, and HagiCode itself is worth paying attention to.

Core Content

Technical Architecture Design

The system uses a clear three-layer architecture to separate concerns, with each layer having clear responsibility boundaries:

HagiCode.Libs layer: This layer is already complete, providing the abstraction and specific implementation of the CLI provider. It defines the ICliProvider<ReasonixOptions> interface, implements ReasonixProvider to handle ACP streaming and session management, and supports parameters like effort, budget, yolo, transcript, and so on. The responsibility of this layer is to provide stable, reusable low-level capabilities without involving any business logic. It's like the foundation of a house—though invisible, it's very important.

hagicode-core layer: This is the focus of our integration. It's responsible for bridging the low-level abstraction to the system's unified interface. Specific work includes registering the AIProviderType.ReasonixCli = 12 enum value, creating ReasonixCliProvider as a thin adapter to bridge the Libs layer, implementing ReasonixGrain to handle session state and execution flow, and integrating the Hero system for parameter mapping and configuration management. The core of this layer is coordinating components to build a complete business chain. It's like the load-bearing walls of a house, connecting all parts together.

web layer: Responsible for displaying and collecting configurations from users. We need to regenerate OpenAPI types to support the new enum value, implement visual type mapping to give Reasonix its own icon and display name, create a CLI parameter configuration form allowing users to configure various parameters, and add multi-language support. The focus of this layer is user experience and interaction design. It's like the decoration of a house—whether it's done well directly affects how comfortable it is to live in.

Such layered design allows each layer to focus on its own responsibilities, reducing system complexity and facilitating subsequent maintenance and expansion. Actually, many times, clarifying things makes them simpler.

Key Technical Decisions

During implementation, we made several key technical decisions that had important impacts on the final architecture and user experience.

Decision 1: Use a Dedicated Grain

We created an independent ReasonixGrain : IReasonixGrain, IExecutorStreamGrain rather than trying to reuse some shared Grain. This decision follows the established pattern of the system's existing 11 providers. While there might be some code duplication, a dedicated Grain allows us to have fine-grained control over Reasonix's specific features, such as its unique session binding mechanism and ACP message mapping. We also defined an empty response DTO ReasonixResponse as a type discriminator. Although it doesn't contain actual data, it plays an important role in the type system. It's like everyone having their own room—even if empty, it's their own space.

Decision 2: Don't Create a Dedicated Settings Class

Unlike some Providers that need connection strings, all Reasonix configurations are set by the user at runtime and don't require startup validation. Therefore, we didn't create a dedicated Settings class. Instead, we store all configurations in the AIProviderOptions.Providers[ReasonixCli].Settings dictionary. This pattern is consistent with other local CLI Providers like Qoder, Kiro, and Kimi, simplifying code structure and avoiding unnecessary abstraction layers. Supported setting keys include: effort, budgetUsd, transcriptPath, enableYolo, arguments, startupTimeoutMs, reasoning. Sometimes simpler is better.

Decision 3: Provider Strategy Health Monitoring

Reasonix is a CLI installed locally by the user—it might not be installed at all, or might not be in the system PATH. In such cases, we shouldn't directly error out but should handle it gracefully with degradation. We use the Provider strategy to check if the CLI is available through CommandUtil.TryResolveExecutablePath. If the check fails, the UI displays as "unavailable" but doesn't affect other parts of the system. This design makes the system more robust and provides clear feedback to users. After all, no one wants the entire system to crash because of a minor issue.

Decision 4: Economic System Classification

In the HagiCode system, different Providers have different economic system classifications. We decided to let Reasonix use the 'claude' economic system classification by default, since Reasonix itself is compatible with the anthropic series of models. Currently, only Codex and Copilot have dedicated economic system classifications, while other Providers reuse existing classifications. This maintains system simplicity while correctly handling billing and cost statistics. Reusing is also a kind of wisdom—not everything needs to start from scratch.

Decision 5: Model Compatibility

Reasonix supports multiple models through the --model flag, especially the anthropic series. We added compatibility mapping in secondary-professions.index.json, allowing users to select these models in Reasonix. This design respects Reasonix's capabilities while maintaining system consistency. Users don't need to understand the underlying differences to smoothly use various models. Users have it hard enough—let's keep things simple for them.

Backend Implementation Details

Backend implementation is divided into several key parts, each with its own unique technical points.

Enum and Type Registration

First, we need to register the new Provider type in the system:

// AIProviderType.cs
public enum AIProviderType
{
    // ... other providers
    ReasonixCli = 12,
}

// AIProviderTypeExtensions.cs
private static readonly Dictionary<string, AIProviderType> _typeMap = new()
{
    // ... other mappings
    ["Reasonix"] = AIProviderType.ReasonixCli,
    ["reasonix"] = AIProviderType.ReasonixCli,
    ["reasonix-cli"] = AIProviderType.ReasonixCli,
    ["ReasonixCli"] = AIProviderType.ReasonixCli,
};

This enum value needs to coordinate with other concurrent changes to avoid conflicts. We chose the value 12 because it's the next available number. It's like lining up—there has to be some order.

Thin Adapter Implementation

ReasonixCliProvider is the key component connecting the Libs layer and the system's unified interface:

public sealed class ReasonixCliProvider : IAIProvider, IVersionedAIProvider, IAsyncDisposable
{
    private static readonly IReadOnlyList<string> SupportedSettingKeys =
    [
        "effort",
        "budgetUsd",
        "transcriptPath",
        "enableYolo",
        "arguments",
        "startupTimeoutMs",
        "reasoning"
    ];

    private readonly ICliProvider<ReasonixOptions> _provider;
    private readonly ConcurrentDictionary<string, string> _sessionBindings = new(StringComparer.Ordinal);

    public async IAsyncEnumerable<AIStreamingChunk> StreamCoreAsync(
        AIRequest request,
        string? sessionId = null,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        var options = BuildOptions(request, sessionId);
        await foreach (var message in _provider.StreamAsync(options, cancellationToken))
        {
            yield return MapToStreamingChunk(message);
        }
    }

    private ReasonixOptions BuildOptions(AIRequest request, string? sessionId)
    {
        return new ReasonixOptions
        {
            ExecutablePath = GetExecutablePath(),
            WorkingDirectory = GetWorkingDirectory(),
            Model = _config.Model,
            Effort = _config.Settings.GetValueOrDefault("effort", "medium"),
            Budget = _config.Settings.GetValueOrDefault("budgetUsd", 10.0),
            Yolo = _config.Settings.GetValueOrDefault("enableYolo", false),
            TranscriptPath = _config.Settings.GetValueOrDefault("transcriptPath"),
            Arguments = _config.Settings.GetValueOrDefault("arguments", ""),
            StartupTimeout = GetStartupTimeout(),
            EnvironmentVariables = _environmentVariables,
            CessionId = sessionId ?? GetCessionId()
        };
    }
}

The key responsibilities of this adapter are:

Validate configuration parameters and reject unsupported setting keys
Maintain session binding relationships, supporting session resumption
Map ACP messages to the system's unified format
Use ProviderErrorAutoRetryCoordinator to implement automatic retry

It's like a translator, translating one language to another while ensuring the meaning is accurate.

Orleans Grain Implementation

ReasonixGrain is responsible for handling session state and execution flow:

public class ReasonixGrain : Grain, IReasonixGrain, IExecutorStreamGrain
{
    private readonly Dictionary<string, ExecutorToolLifecycleStatus> _toolLifecycleState =
        new(StringComparer.Ordinal);

    public IAsyncEnumerable<ReasonixResponse> ExecuteCommandStreamAsync(
        string command,
        string? heroId = null,
        CancellationToken token = default,
        string? executionMessageId = null,
        string? systemMessage = null,
        Dictionary<string, string>? requestSettings = null)
    {
        var request = BuildRequest(command, isEdit: false, heroId, executionMessageId, systemMessage, requestSettings);
        return SendAsync(request, heroId, token);
    }

    private async IAsyncEnumerable<ReasonixResponse> SendAsync(
        AIRequest request,
        string? heroId,
        [EnumeratorCancellation] CancellationToken token)
    {
        _cancellationTokenSource = new CancellationTokenSource();
        var linkedToken = CancellationTokenSource.CreateLinkedTokenSource(token, _cancellationTokenSource.Token);

        var provider = await ResolveReasonixProviderAsync(heroId);

        await foreach (var chunk in provider.StreamAsync(request, linkedToken.Token))
        {
            var response = BuildChunkResponse(chunk);
            yield return response;
        }
    }

    private async Task<IAIProvider> ResolveReasonixProviderAsync(string? heroId)
    {
        // Hero-aware configuration fallback logic
        var config = await HeroProviderResolver.ResolveAsync(AIProviderType.ReasonixCli, heroId);
        return _aiProviderFactory.CreateProvider(AIProviderType.ReasonixCli, config);
    }
}

The core functions of the Grain include:

Use [PersistentState("reasonix-interop")] to maintain session state
Implement Hero-aware configuration fallback logic
Track tool lifecycle status
Support cancellation token chains, ensuring execution can be interrupted in a timely manner

It's like a housekeeper, arranging things in an orderly manner.

Hero System Integration

The Hero system is HagiCode's profession configuration system, and we need to integrate Reasonix into this system:

// HeroAppService.cs
// Family inference
AIProviderType.ReasonixCli => "reasonix"

// Managed CLI parameters
ManagedCliParameterKeysByProvider[AIProviderType.ReasonixCli] = 
    ["binary", "effort", "budgetUsd", "transcriptPath", "enableYolo", "arguments", "startupTimeoutMs"];

// Managed model parameters
ManagedModelParameterKeysByProvider[AIProviderType.ReasonixCli] = 
    ["model", "reasoning"];

In the profession directory configuration file main-professions.yaml:

- Id: "profession-reasonix"
  Name: "Reasonix"
  Family: "reasonix"
  Summary: "hero.professionCopy.primary.reasonix.summary"
  Icon: "executor-avatar:Reasonix"
  SourceLabel: "hero.professionCopy.sources.aiProvidersReasonixCli"
  ProviderType: "ReasonixCli"
  SortOrder: 130
  DefaultEnabled: true
  DefaultParameters:
    binary: "reasonix"
    effort: "medium"
    enableYolo: "false"
    startupTimeoutMs: "15000"

With this configuration, users can see the Reasonix option in the Hero configuration interface and make personalized settings. It's like registering someone's household—with an identity, they can live normally in this society.

Frontend Implementation Details

Frontend implementation is mainly responsible for user interaction and display, also divided into several key parts.

Type Generation and Visual Mapping

First, we need to regenerate OpenAPI types:

npm run generate:api:once

This generates type definitions containing REASONIX_CLI = 'ReasonixCli'. Then in visual mapping:

// executorTypeAdapter.ts
export type ExecutorVisualType = 'Claude' | 'Codex' | 'Copilot' | 'Reasonix' | ...;

export const resolveExecutorVisualTypeFromProviderType = (
  providerType: PCode_Models_AIProviderType
): ExecutorVisualType => {
  switch (providerType) {
    // ... other cases
    case PCode_Models_AIProviderType.REASONIX_CLI:
      return 'Reasonix';
  }
};

This way Reasonix has its own visual type and can display corresponding icons and styles. It's like everyone having their own ID photo.

Configuration Form Implementation

In HeroCliEquipmentForm.tsx, we added a dedicated configuration form for Reasonix:

case PCode_Models_AIProviderType.REASONIX_CLI:
  return (
    <>
      <Form.Item name="binary">
        <Input />
      </Form.Item>
      <Form.Item name="effort">
        <Select>
          <Select.Option value="none">None</Select.Option>
          <Select.Option value="low">Low</Select.Option>
          <Select.Option value="medium">Medium</Select.Option>
          <Select.Option value="high">High</Select.Option>
        </Select>
      </Form.Item>
      <Form.Item name="budgetUsd">
        <InputNumber />
      </Form.Item>
      <Form.Item name="transcriptPath">
        <Input />
      </Form.Item>
      <Form.Item name="enableYolo">
        <Switch />
      </Form.Item>
      <Form.Item name="arguments">
        <Input />
      </Form.Item>
      <Form.Item name="startupTimeoutMs">
        <InputNumber />
      </Form.Item>
    </>
  );

This form covers all parameters supported by Reasonix, allowing users to configure according to their needs. It's like tailoring clothes for someone—fit is most important.

Multi-language Support

To enable international users to use it as well, we added multi-language support:

# locales/*/common/hero.yml
profession:
  primary:
    reasonix:
      name: "Reasonix"
      summary: "AI code assistant based on ACP"
      parameters:
        effort: "Computational effort"
        budgetUsd: "Budget (USD)"
        transcriptPath: "Transcript file path"
        enableYolo: "Enable YOLO mode"

After all, if the language doesn't work, even good things can't be used.

Health Monitoring Mapping

The frontend also needs to display Reasonix's health status:

// healthApi.ts
export const MONITORING_CHANNEL_FALLBACKS = {
  // ... other providers
  reasonix: {
    displayName: 'Reasonix',
    icon: 'executor-avatar:Reasonix'
  }
};

export const mapProviderTypeToMonitoringCliId = (
  providerType: PCode_Models_AIProviderType
): string => {
  switch (providerType) {
    // ... other cases
    case PCode_Models_AIProviderType.REASONIX_CLI:
      return 'reasonix';
  }
};

This way users can see Reasonix's status in the monitoring panel. If the CLI is not installed or unavailable, they will receive clear prompts. It's like a doctor examining a patient—catching problems early leads to early treatment.

Best Practices and Considerations

During implementation, we summarized some best practices and points to note.

Parameter Validation

ReasonixCliProvider must strictly validate configuration parameters and reject unsupported setting keys:

public void ValidateConfigurationOverrides(Dictionary<string, string?> overrides)
{
    foreach (var key in overrides.Keys)
    {
        if (!SupportedSettingKeys.Contains(key))
        {
            throw new HeroProviderConfigurationException(
                $"Unsupported setting key '{key}' for Reasonix provider");
        }
    }
}

This prevents users from configuring wrong parameters and avoids runtime errors. It's like a goalkeeper—can't let things that shouldn't enter get in.

Session Binding Management

Use ConcurrentDictionary to manage session bindings, supporting session resumption:

_sessionBindings[cessionId] = sessionId;

// Bind existing sessions in subsequent requests
if (_sessionBindings.TryGetValue(cessionId, out var boundSessionId))
{
    options.SessionId = boundSessionId;
}

This design allows users to resume previous sessions after interruption, providing a better experience. It's like remembering a story so you can continue telling it next time.

Graceful Degradation Handling

The frontend should check CLI availability and provide friendly prompts:

const reasonixAvailable = await healthApi.checkCliAvailable('reasonix');
if (!reasonixAvailable) {
  showMessage('Reasonix CLI is not installed, please configure it in the system PATH');
}

Don't let users encounter inexplicable errors—check in advance and provide clear guidance. After all, no one wants to get stuck inexplicably.

Test Coverage

Comprehensive testing is key to quality assurance:

[Fact]
public async Task ExecuteCommandStreamAsync_WithValidCommand_StreamsReasonixResponse()
{
    // Arrange
    var grain = _grainFactory.GetGrain<IReasonixGrain>("test-cession");
    var responses = new List<ReasonixResponse>();

    // Act
    await foreach (var response in grain.ExecuteCommandStreamAsync("help"))
    {
        responses.Add(response);
    }

    // Assert
    responses.Should().NotBeEmpty();
    responses.All(r => r.Kind == ExecutorResponseKind.Content).Should().BeTrue();
}

Such unit tests can verify that core functions work correctly, preventing regression errors. It's like doing practice questions before an exam—you need to ensure you've actually mastered it.

Summary

Through this Reasonix integration practice, we successfully elevated a local CLI tool to the system's first-class Agent Provider. Throughout the process, we followed established architecture patterns, made reasonable technical decisions, and ultimately implemented a complete, well-integrated solution with good user experience.

The core value of this solution lies in:

Clear three-layer architecture separates concerns and reduces complexity
Dedicated Grain and thin adapter design maintains flexibility
Graceful degradation and health monitoring improve user experience
Comprehensive parameter validation and session management ensure reliability

For other similar CLI Provider integrations, this solution provides a reusable pattern. We hope this practice can help other developers, and we welcome everyone to exchange experiences in the HagiCode project.

Actually, many things are like this—at first they seem difficult, but as long as you find the right method and take it step by step, you can always solve it. It's like climbing a mountain—the peak looks far away, but as long as you don't give up, you can always climb up.

Summary

Returning to the theme "From Scratch: How to Integrate Reasonix CLI into the HagiCode System," what's truly worth repeatedly confirming isn't scattered techniques, but whether constraint conditions, implementation boundaries, and engineering trade-offs have been clearly understood.

As long as the judgment bases in the article are distilled into stable checklist items, you can make reliable decisions more quickly when facing similar problems in the future.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-09-integrating-reasonix-cli-into-hagicode%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Practical Journey of Integrating Pi Agent into HagiCode

Hagicode — Mon, 08 Jun 2026 12:20:30 +0000

Practical Journey of Integrating Pi Agent into HagiCode

This article shares our practical experience in integrating Pi agent as a first-class workflow entry point in the HagiCode project, including architecture design, core component implementation, and frontend and backend adaptation details.

Background

Actually, everything started with that question: in the HagiCode Mono project, although repos/Hagicode.Libs already implemented the reusable PiProvider, repos/hagicode-core and repos/web had not yet elevated Pi to a project-level first-class Agent CLI. This is like having a good pair of shoes but not tying the laces properly—you can walk, but it always feels like something is missing.

The existing PiProvider is located at HagiCode.Libs/src/HagiCode.Libs.Providers/Pi/PiProvider.cs. It implements a CLI communication protocol based on line-delimited JSON (--mode json --print), supporting session management, tool calls, and streaming output. This code is well-written, but it's just lying there, not yet awakened.

This situation created a gap: Pi's underlying capabilities were complete, but the project-level integration chain (from user configuration to execution monitoring) was missing. It's like painting a good picture but not hanging it on the wall for people to appreciate. Therefore, we needed to integrate Pi as a new active provider PiCli into the entire system, making it a first-class workflow entry point like other Agent CLIs.

After all, what we wanted was a complete experience, not scattered fragments.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an intelligent code assistant project, and during development we needed to integrate multiple AI capability providers. The Pi agent integration solution described in this article is a reusable integration pattern summarized from our practice, which has reference value for similar multi-provider integration scenarios. The project's GitHub address is github.com/HagiCode-org/site.

Architecture Design

Pi agent integration adopted the thin adapter pattern, rather than re-implementing the Pi process protocol at the core layer. This design decision is not complex—we just thought, why reinvent the wheel?

After all:

Avoid duplicate implementation: The parameter building, process launching, JSON parsing, and error handling logic in PiProvider are already complete. Re-implementing would create two sources of behavior and two test matrices. That's fine, but maintenance would be troublesome.
Maintain consistency: Consistent with the integration methods of existing CLIs like Kimi, Gemini, Reasonix, and DeepAgents—all delegate through thin adapters to the libs layer implementation. Everyone does this, just follow along.
Separation of concerns: hagicode-core focuses on runtime contracts and business logic, while process details are left to HagiCode.Libs. Each does their own job, isn't that beautiful?

This design allows HagiCode to quickly integrate new AI capability providers while keeping the core layer clean. After all, simplicity is beauty, and efficiency is money.

Core Component Implementation

Provider Enumeration and Factory

Added PiCli = 13 enumeration value in hagicode-core/src/PCode.Models/AIProviderType.cs:

public enum AIProviderType
{
    ClaudeCodeCli = 0,
    // ... other providers
    PiCli = 13,
}

This enumeration value is the root of the provider identity, affecting the OpenAPI-generated PCode_Models_AIProviderType.ts frontend enumeration, the creation branch of AIProviderFactory, and Provider parsing and active provider judgment logic. Register the new creation branch in AIProviderFactory:

case AIProviderType.PiCli:
    provider = new PiCliProvider(
        logger,
        configuration,
        providerFactory.GetRequiredService<ICliProvider<PiOptions>>(),
        providerFactory.GetService<IAgentCliRuntimeEnvironmentResolver>());
    break;

Actually, this code is nothing special, just an enumeration plus a switch case. But they are important, like notes on a musical score—adding them one by one creates a complete melody.

Thin Adapter Implementation

PiCliProvider.cs is the core thin adapter, implementing the IAIProvider, IVersionedAIProvider, and IAsyncDisposable interfaces. It receives ICliProvider<PiOptions> (from HagiCode.Libs) through the constructor, maps AIRequest / ProviderConfiguration to PiOptions, and then delegates operations like execution, ping, and version query to the underlying provider.

The key is to handle Pi's unique JSON event stream, including assistant.thought, assistant, terminal.completed, and other events. These events need to be correctly parsed and converted to the system's standard format during streaming output. It's a bit like translation—conveying meaning from one language to another.

Main Profession Preset

Added profession-pi main profession entry in main-professions.yaml:

- Id: "profession-pi"
  Name: "Pi"
  Family: "pi"
  Summary: "hero.professionCopy.primary.pi.summary"
  Icon: "executor-avatar:Pi"
  SourceLabel: "hero.professionCopy.sources.aiProvidersPiCli"
  ProviderType: "PiCli"
  SortOrder: 59
  DefaultEnabled: true
  DefaultParameters:
    binary: "pi"
    provider: "omniroute"
    thinking: "balanced"

This ensures that the backend snapshot and frontend fallback directory have consistent Pi identity, allowing Pi configuration to be managed through the existing Hero editor, and Pi's addition won't break the consumability of existing main profession entries. After all, we don't want to break existing things just because we added a new feature—that would be penny-wise and pound-foolish.

Monitoring Registry

AgentCliMonitoringRegistry needs to add Pi's monitoring descriptor so the system can parse executable paths, display brand names, perform health probes, and display Pi status in the status bar and health details:

new AgentCliMonitoringDescriptor(
    CliId: "pi",
    DisplayName: "Pi",
    ProviderType: AIProviderType.PiCli,
    DisplayOrder: 13,
    Strategy: AgentCliMonitoringStrategy.Grain,
    NotConfiguredMessage: "Pi CLI is not configured or executable not found.",
    EnabledPaths: [],
    ExecutablePathConfigPaths: ["Hero:PrimaryProfessions:Pi:ExecutablePath"],
    DefaultExecutablePath: "pi")

The monitoring system is like a dashboard, telling you how the car is running. Pi's status is clear at a glance, so users can know if everything is normal.

Frontend Adaptation

Executor Type Adaptation

The frontend needs to update executorTypeAdapter.ts, adding Pi's type recognition logic:

const PI_IDS = new Set<string>([
  PCode_Models_AIProviderType.PI_CLI,
  'Pi',
  'PiCli',
  'pi',
  'picli',
  'pi-cli',
]);

export function isPi(value: string): boolean {
  const normalized = normalize(value);
  const normalizedLower = normalized.toLowerCase();
  return PI_IDS.has(normalized)
    || normalizedLower.includes('pi-cli')
    || normalizedLower.includes('picli')
    || normalizedLower === 'pi';
}

This is like giving Pi several names—no matter what you call it, it knows you're referring to it. After all, what you call it doesn't matter, what matters is knowing who it is.

Fallback Hero Directory

Add Pi's fallback entry in hero.ts to ensure that even if backend data is not loaded, the frontend can still display Pi configuration normally:

{
  id: "profession-pi",
  name: "Pi",
  family: "pi",
  summary: "hero.professionCopy.primary.pi.summary",
  icon: "executor-avatar:Pi",
  sourceLabel: "hero.professionCopy.sources.aiProvidersPiCli",
  providerType: AIProviderType.PI_CLI,
  sortOrder: 59,
  isReadOnly: true,
  managedParameterKeys: {
    // parameter keys supported in the first version
  },
  defaultParameters: {
    binary: "pi",
    provider: "omniroute",
    thinking: "balanced",
  },
}

Fallback is like a backup plan—just in case the backend goes down or data doesn't load, the frontend can still work normally. After all, no one wants to be in a panic when that happens.

Localization Copy and Forms

Add Pi-related translations in locales/*/common/{hero,settings}.yml, and add a configuration field block for Pi in HeroCliEquipmentForm.tsx, supporting binary, provider, thinking, sessionDirectory, and tool/session switch fields.

The first version of Pi only exposes the minimum necessary fields. Complex features like tool allowlist/denylist and environment variable editors are explicitly deferred to subsequent changes. After all, you can't become fat in one bite, take it slow and go faster.

Configuration Examples

Backend Configuration

Configure Pi parameters in appsettings.yml:

Hero:
  PrimaryProfessions:
    Pi:
      ExecutablePath: /usr/local/bin/pi
      Provider: omniroute
      Thinking: balanced
      SessionDirectory: ~/.pi/sessions
      NoSession: false
      DisableAllTools: false
      DisableBuiltinTools: false

Frontend Configuration

Configure Pi profession in the Hero editor:

{
  id: "my-pi-profession",
  name: "My Pi Profession",
  family: "pi",
  providerType: AIProviderType.PI_CLI,
  primaryModel: {
    provider: "PiCli",
    model: "glm-4.7",
    providerSettings: {
      provider: "omniroute",
      thinking: "balanced",
      sessionDirectory: "/Users/username/.pi/sessions",
      noSession: false,
      disableAllTools: false,
      disableBuiltinTools: false,
    },
  },
}

Configuration files are like recipes—follow them and you'll make good food. But sometimes, even following the recipe, you can still burn the food... though this configuration is quite clear, so there shouldn't be any problems.

Validation and Testing

Backend Validation

Validate main profession presets in tests:

var snapshot = await presetProvider.GetSnapshotAsync();
var piProfession = snapshot.FindById("profession-pi");
piProfession.ShouldNotBeNull();
piProfession.ProviderType.ShouldBe(AIProviderType.PiCli);
piProfession.Family.ShouldBe("pi");

Also need to verify Pi availability and health check:

# Check Pi executable
which pi
pi --version

# Verify backend provider registration
curl http://localhost:35168/api/health/agent-cli/pi

Testing is like exams—passing means you really know it. But sometimes, passing an exam doesn't mean you really understand it, but at least it shows you can get the answers right.

Frontend Validation

// Verify type parsing and display name
expect(resolveExecutorVisualType('pi-cli')).toBe('Pi');
expect(resolveExecutorVisualType(PCode_Models_AIProviderType.PI_CLI)).toBe('Pi');
expect(resolveExecutorDisplayName('PiCli')).toBe('Pi');

// Verify fallback directory
const piFallback = findFallbackProfessionById('profession-pi');
expect(piFallback?.providerType).toBe(AIProviderType.PI_CLI);

These test cases cover the main logic paths, ensuring Pi can be correctly identified and displayed. After all, things shown to users can't have errors.

Common Troubleshooting

Pi Executable Not Found

If the health check returns "Pi executable was not found.", you need to check if pi is in PATH, or confirm if the configured path is correct. The solution is to ensure pi is installed and in PATH, or configure the correct ExecutablePath in appsettings.yml.

This is like not being able to find your house keys—you need to think if you put them in the wrong place. Actually, the solution is simple—either put the keys back in the original place, or get a new lock.

Configuration Fields Not Recognized

If you get the error "PiCli runtime settings [...] are not supported" at startup, check if you're only using the configuration fields supported in the first version. Fields supported in the first version include: provider, thinking, sessionDirectory, noSession, disableAllTools, disableBuiltinTools.

Sometimes it's just being greedy—wanting too many features, but the system doesn't support them. Actually, the first version's features are already enough; you can't chew too much at once.

Cannot Select Pi in Frontend

If there's no Pi option in the Hero editor, check if you've run npm run generate:api to regenerate the frontend enumeration, whether there's a profession-pi entry in hero.ts, and whether the localization copy is added correctly.

Troubleshooting is like finding a lost item—you have to do it step by step. After all, blind searching won't find it; you need to search logically.

Best Practices

Use thin adapter pattern: Don't re-implement the process protocol at the core layer; delegate to the libs layer provider. This avoids duplicate implementation and maintains code consistency. After all, reinventing the wheel is not only tiring but also prone to problems.
Maintain naming consistency: Use consistent naming conventions across frontend and backend to avoid confusion. Provider enumeration uses PiCli, CLI ID uses "pi", display name uses "Pi". Good names mean lower communication costs.
Prioritize presets: The first version should be based on the profession-pi preset, rather than requiring users to manually configure. This allows users to get started quickly and reduces configuration complexity. Users like simple things; leave the complex ones to me.
Focus on error messages: Ensure error messages are clear and actionable, helping users quickly locate problems. Clear error messages mean users won't panic over a single error.
Version compatibility: Consider the serialization stability of AIProviderType enumeration values; changes need to be handled carefully. The AIProviderType.PiCli = 13 enumeration value cannot be easily modified. After all, changing this value might break backward compatibility—that would be troublesome.

Summary

Through the thin adapter pattern, we successfully integrated Pi agent into the HagiCode system, making it a first-class workflow entry point like other Agent CLIs. The core advantages of this solution are:

Avoided duplicate implementation and reused the existing PiProvider from the libs layer
Maintained consistent integration methods with existing providers, reducing maintenance costs
Implemented a complete chain from user configuration to execution monitoring

HagiCode's practice proves that the thin adapter pattern is an effective solution for integrating AI capability providers. It enables us to quickly support new agents while maintaining system stability and maintainability.

Actually, doing technology is like this—find a good pattern, then reuse it. This allows you to move forward quickly without losing direction. Like walking—once you find a good path, keep walking on it, just occasionally stop to enjoy the scenery...

If you're also doing multi-provider AI capability integration, I hope this solution gives you some inspiration. If you're interested in the HagiCode project, welcome to exchange on GitHub. After all, technology makes progress through communication.

References

Summary

Around "Practical Journey of Integrating Pi Agent into HagiCode," a more robust approach is to first run through key configurations, dependency boundaries, and implementation paths step by step, then fill in optimization details.

When goals, steps, and acceptance criteria are clear, such solutions can more smoothly enter actual delivery.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-08-integrating-pi-agent-into-hagicode%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Automated Windows App Deployment to Microsoft Store

Hagicode — Wed, 20 May 2026 10:18:56 +0000

Automated Windows App Deployment to Microsoft Store

How to achieve end-to-end automation from version parsing to Store release, saying goodbye to tedious manual operations.

Background

If you have an Electron application you want to list on the Microsoft Store, you'll likely run into this problem: the Store doesn't support separate installation processes—you have to package the desktop application and server payload together into a complete AppX/MSIX package.

That would be manageable enough. But the problem continues. Each time you release a new version, you need to:

Check if desktop and server versions have been updated
Check out code from the corresponding tags
Download and inject the server payload
Build the MSIX package
Manually upload to the Microsoft Store
Configure store information and pricing

If every step requires manual operation, that's too much hassle. And it's error-prone—you might not even remember which steps you've completed and which you haven't.

Actually, this isn't really anyone's fault—manual operations are naturally prone to omissions. It's just that we really didn't want to go through this hassle every time, so we decided to solve this problem once and for all—by automating the entire process.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. As an AI code assistant, HagiCode provides both desktop and web clients and needs to support multiple distribution channels. In implementing automated Windows Store deployment, we've developed a complete automation solution.

Speaking of which, this was probably an unexpected bonus. What started as a simple time-saver ended up becoming this comprehensive solution.

Technical Architecture Analysis

This problem actually involves coordinating multiple technical layers. We can break it down into five layers:

Version Coordination Layer

First, we need to know when a new version needs to be released. We need to parse the latest versions of desktop and server components from an Azure index (a blob storage we use to store build artifacts), then determine whether a new Store package needs to be generated.

It's like asking yourself: Is it time to do this now?

Workspace Management Layer

AppX builds depend on source code-level configuration and runtime layout, so we can't simply repackage existing build artifacts. We need to check out code from a specific tag in the desktop repository to ensure the correct source code state is used for the build.

After all, if the source code is wrong, everything else is wasted effort.

Runtime Packaging Layer

This is the core part. We need to inject the server payload into the desktop application's packaging layout. This way, when the application starts, it will detect the packaged runtime and enter Steam mode (offline mode).

If this step isn't done well, all previous efforts are wasted.

Build Output Layer

Use electron-builder to generate an MSIX package that meets Store requirements. This step needs to run in a Windows environment because AppX builds require the Windows SDK.

Some things just need to be done in the right place—won't work elsewhere.

Distribution Layer

Finally, publish to GitHub Releases and the Microsoft Store. GitHub Release serves as backup and version tracking, while the Microsoft Store is面向终端用户.

Everything is ready, just needs this final push.

Overall Architecture Design

┌─────────────────────────────────────────────────────────────┐
│                    package-release workflow                  │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │ resolve_plan    │───▶│   build         │                │
│  │ (Version parsing & skipping) │    │   (MSIX build)    │                │
│  └─────────────────┘    └────────┬────────┘                │
│         │                       │                          │
│         ▼                       ▼                          │
│  ┌─────────────────┐    ┌─────────────────┐                │
│  │ skip_summary    │    │   publish       │                │
│  │ (Skip report)   │    │   (Publish)     │                │
│  └─────────────────┘    └────────┬────────┘                │
│                                 │                          │
│                                 ▼                          │
│                        ┌─────────────────┐                 │
│                        │ publish_store   │                 │
│                        │ (Store publish) │                 │
│                        └─────────────────┘                 │
└─────────────────────────────────────────────────────────────┘

The entire process is driven by GitHub Actions and can be triggered on a schedule (every 4 hours) or manually. When manually triggered, you can specify specific desktop and server versions, or force a rebuild.

Actually, once every four hours isn't that frequent—code updates vary in speed, but this approach is safer.

Implementation Details

1. Build Plan Resolution

The first step is to determine whether a new version needs to be built. We need to parse the current versions of desktop and server components, then check whether a corresponding release already exists.

// scripts/resolve-dispatch-build-plan.mjs
export async function resolveDispatchBuildPlan({
  eventName,
  eventPayload,
  desktopAzureSasUrl,
  serverAzureSasUrl,
}) {
  // Parse trigger inputs
  const trigger = normalizeTriggerInputs({ eventName, eventPayload });

  // Parse desktop and server versions from Azure index
  const [desktopRelease, serverRelease] = await Promise.all([
    resolveIndexRelease({ 
      azureSasUrl: desktopAzureSasUrl,
      platformId: 'win-x64' 
    }),
    resolveIndexRelease({ 
      azureSasUrl: serverAzureSasUrl,
      platformId: 'win-x64' 
    })
  ]);

  // Generate release tag
  const desktopTag = normalizeGitTag(desktopRelease.version);
  const releaseTag = deriveStoreReleaseTag(desktopRelease.version, serverRelease.version);
  // For example: desktop-v1.2.3-server-v4.5.6

  // Check if already exists (avoid duplicate builds)
  const existingRelease = await findReleaseByTag(packerRepository, releaseTag);
  const shouldBuild = !existingRelease || trigger.forceRebuild;

  return {
    release: { tag: releaseTag, exists: Boolean(existingRelease) },
    build: { shouldBuild, skipReason },
    upstream: { desktop: { tag: desktopTag }, server }
  };
}

The key in this step is the skip logic—if the same version combination has already been built, there's no need to run the entire build process again. This saves CI costs and time.

Doing the same thing repeatedly probably doesn't make much sense. After all, time and resources are limited.

2. Workspace Preparation

Once you've decided to build, you need to prepare a clean build environment. We use git worktree to check out code from a specific tag.

// scripts/prepare-packaging-workspace.mjs
export async function preparePackagingWorkspace({
  planPath,
  platformId,
  workspacePath,
  desktopSourcePath
}) {
  // Use git worktree to check out desktop code from specific tag
  await runCommand('git', [
    '-C', resolvedDesktopSourcePath,
    'worktree', 'add', '--detach',
    desktopWorkspace,
    `refs/tags/${plan.upstream.desktop.tag}`
  ]);

  // Validate workspace
  const validation = await validateDesktopWorkspace({
    desktopWorkspace,
    storePackageConfig
  });

  // Create workspace manifest
  const workspaceManifest = {
    desktopWorkspace,
    runtimeInjectionRoot: validation.runtimeRoot,
    desktopTag: plan.upstream.desktop.tag,
    desktopRef,
  };

  return workspaceManifest;
}

The advantage of using worktree is that it doesn't affect the main working directory, builds can run in parallel, and it's easy to clean up after the build completes.

After all, no one wants their main working directory messed up because of a build.

3. Server Payload Injection

This step downloads and injects the server payload into the correct location.

// scripts/stage-server-payload.mjs
export async function stageServerPayload({
  planPath,
  workspacePath,
  platformId,
  azureSasUrl
}) {
  // Download server payload from Azure index
  const assetSource = resolveAssetDownloadUrl({ asset, sasUrl: azureSasUrl });
  await downloadFromSource({ 
    sourceUrl: assetSource, 
    destinationPath: downloadPath 
  });

  // Extract and validate
  await extractArchive(downloadPath, extractionPath);
  const runtimeRoot = await resolveRuntimeRoot(extractionPath);
  const validation = await validateServerPayloadRoot(runtimeRoot, platformId);

  // Inject into packaging runtime layout
  // Target path is resources/portable-fixed/current
  // This path will be mapped to extra/portable-fixed/current in AppX
  await copyDir(runtimeRoot, targetPath);
}

The key is the path mapping—resources/portable-fixed/current gets packaged to extra/portable-fixed/current in the AppX, so the application detects the local runtime at startup and enters offline mode.

Paths are unforgiving—one wrong character and it won't be found.

4. MSIX Build

With the prepared workspace and server payload, you can build the MSIX package.

// scripts/build-appx.mjs
export async function buildAppx({
  planPath,
  workspacePath,
  platformId
}) {
  // Generate Store-specific electron-builder config overlay
  const overlayConfig = await writeStoreElectronBuilderConfig({
    desktopWorkspace: workspaceManifest.desktopWorkspace,
    sourceConfigPath: storePackageConfig.desktop.electronBuilderConfigPath,
    outputConfigPath: 'electron-builder.store.yml'
  });

  // Run desktop build command
  await runShellCommand(
    buildDesktopStoreCommand(overlayConfig.outputPath, desktopScripts),
    workspaceManifest.desktopWorkspace
  );

  // Collect MSIX output
  const storeOutputs = await findStoreOutputs(pkgDirectory);
  const artifactPath = path.join(
    workspaceManifest.outputDirectory, 
    artifactFileName
  );
  await copySingleFile(primaryOutput, artifactPath);
}

The electron-builder configuration needs to include Store-specific metadata like package identity, publisher display name, etc. This information will be used during Store submission.

If the configuration is wrong, the package won't build. Nothing more to say about that.

5. Publishing to GitHub

After the build completes, you need to publish the artifacts to GitHub Releases.

// scripts/publish-release.mjs
export async function publishRelease({
  planPath,
  artifactsDir,
  outputDir,
  forceDryRun
}) {
  // Build publication artifact manifest
  const publicationArtifacts = await buildPublicationArtifacts({
    plan,
    artifactsDir,
    outputDir
  });

  if (!dryRun) {
    // Create or update GitHub Release
    const releaseResult = await upsertReleaseNotes(
      plan.release.repository,
      plan.release.tag,
      token,
      { name, body }
    );

    // Upload assets
    for (const upload of publicationArtifacts.uploads) {
      await uploadReleaseAsset({
        release: releaseResult.release,
        filePath: upload.filePath,
        fileName: upload.fileName
      });
    }
  }
}

GitHub Release serves as version tracking and backup—even if the Store publication fails, the build artifacts are preserved.

It's always good to have a backup plan. What if you need to roll back someday?

6. Publishing to Microsoft Store

The final step is publishing to the Store using the Microsoft Store CLI.

# .github/workflows/package-release.yml
publish_store:
  runs-on: windows-latest
  steps:
    - name: Configure Microsoft Store CLI
      uses: microsoft/microsoft-store-apppublisher@v1.2

    - name: Publish MSIX packages to Store
      shell: pwsh
      run: |
        msstore reconfigure --tenantId $env:AZURE_AD_TENANT_ID ...
        msstore publish "$($package.FullName)" -id $env:MICROSOFT_STORE_PRODUCT_ID

This step needs to run on a Windows runner because the Microsoft Store CLI requires a Windows environment.

Some things just need to be done in the right place—won't work in a different environment.

Practical Guide

Configuration Files

The Store package configuration file defines package identity and build settings:

{
  "packageIdentity": {
    "displayName": "Hagicode",
    "publisherDisplayName": "newbe36524",
    "publisher": "CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F",
    "identityName": "newbe36524.Hagicode",
    "backgroundColor": "transparent",
    "languages": ["en-US", "zh-CN", "zh-Hant"]
  },
  "supportedWindowsTargets": ["win-x64"],
  "desktop": {
    "submodulePath": "inputs/hagicode-desktop",
    "electronBuilderConfigPath": "electron-builder.yml",
    "buildScript": "build:appx",
    "runtimeInjectionPath": "resources/portable-fixed/current"
  }
}

Configuration is painful to change, so it's best to get it right the first time.

Workflow Triggers

Can be triggered on schedule or manually:

on:
  schedule:
    - cron: '0 */4 * * *'  # Run every 4 hours
  workflow_dispatch:
    inputs:
      desktop_version:
        description: 'Desktop version selector'
        required: false
      server_version:
        description: 'Server version selector'
        required: false
      force_rebuild:
        description: 'Force rebuild even if exists'
        type: boolean
      dry_run:
        description: 'Build only, do not publish'
        type: boolean

Automatic or manual, as long as it runs in the end.

Key Considerations

Git Tag Requirements: The desktop repository must contain tags corresponding to release versions (e.g., v1.2.3), otherwise the build will fail
Azure SAS URL: Need to configure DESKTOP_AZURE_SAS_URL and SERVER_AZURE_SAS_URL environment variables to access the index
Microsoft Store Credentials: Need to configure the following secrets:
- AZURE_AD_APPLICATION_CLIENT_ID
- AZURE_AD_APPLICATION_SECRET
- AZURE_AD_TENANT_ID
- SELLER_ID
- MICROSOFT_STORE_PRODUCT_ID
Runtime Validation: Server payload must contain required runtime files, otherwise packaging will fail
Windows Runner: AppX builds and Store publishing need to run on Windows runners
Duplicate Detection: Scheduled runs check for existing release tags to avoid unnecessary builds

We've probably stepped on all these pits, so writing them down as a reminder. After all, who wants to make the same mistakes twice?

Summary

Windows Store automated deployment looks complex, but when broken down into independent steps, each step isn't difficult. The key is:

Use git worktree to manage build environments
Inject server payload into the correct path
Use electron-builder to generate MSIX packages
Use Store CLI for final publishing

This solution has been running stably in the HagiCode project for several months, basically achieving the goal of "full automation"—except for initial credential and setup configuration, subsequent version releases require no manual intervention.

Actually, many things are like this—they look difficult but are straightforward to do. It just takes some patience and experimentation.

If you're working on similar automation, I hope this article provides some reference. Of course, every project is different and may need adjustments based on specific requirements.

After all, all roads lead to Rome—some roads are just easier to travel than others...

References

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-05-20-windows-app-automation-to-microsoft-store%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

OpenCode Integration Practice: Architectural Evolution from Standalone Process to Shared Runtime

Hagicode — Mon, 11 May 2026 03:54:48 +0000

OpenCode Integration Practice: Architectural Evolution from Standalone Process to Shared Runtime

This article shares the complete practice of HagiCode integrating the OpenCode AI assistant, including key design decisions during the architectural evolution process, pitfalls encountered, and final solutions.

Background

OpenCode is an open-source AI coding assistant project hosted on GitHub. For a monorepo project like HagiCode, integrating OpenCode as a supported AI Provider means it can be used as a backend model for proposal generation, code editing, and workflow execution.

However, this integration process didn't go as smoothly as imagined. Early on, there were two separate proposals: one planned to create a C# SDK, which was later abandoned—not really a loss; another for repository-level integration did persist. As OpenCode entered the formal session pipeline, we encountered a series of issues like session management and error recovery—after all, what must come will come.

More troublesome was that the initially designed "standalone process per session" model exposed high resource overhead issues in actual operation, forcing a refactor to a "system-level shared runtime" model. We also stepped into the 400 BadRequest pit—reusing external endpoints lacking context causing request failures. It's all tears, really.

This article is just organizing these pitfalls and design decisions to provide reference for projects that need to integrate OpenCode in the future. After all, beautiful things or people don't necessarily need to be possessed—as long as she remains beautiful, just watching her beauty quietly is enough... Technical sharing is the same.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI-based code assistant project. During development, we needed to integrate multiple AI Providers, and OpenCode is one of them. The architectural evolution process shared below are all real experiences from our actual project—stepping in pits and optimizing them. No choice but to fill the pits we stepped in.

Technical Architecture

Overall Layered Design

HagiCode's OpenCode integration architecture is divided into five layers, each with clear responsibilities:

1. Repository Integration Layer

Register the OpenCode repository through the MonoSpecs configuration system (.hagicode/monospecs.yaml). There's a choice here: submodule or plain Git repository? We chose the latter, managing cloning and synchronization through a unified scripts/clone-repos.mjs script. This is more flexible and avoids the permission and collaboration issues brought by submodules—after all, no one wants to see that error screen, but no choice.

2. Provider Layer

OpenCodeCliProvider implements the IAIProvider interface, which is the standard abstraction layer for interfacing with external AI services. The initial proposal wanted "standalone process per session," but actual operation revealed resource overhead was too high, ultimately changing to shared runtime mode, managing system-level runtime lifecycle through OpenCodeRuntimeCoordinator. It's nothing, really—the idea was beautiful, reality is cruel.

3. Runtime Management Layer

OpenCodeRuntimeCoordinator is the core of the entire architecture, responsible for runtime startup, health checks, and失效重建. It uses HagiCode.Libs.Providers.OpenCode as the HTTP client foundation, encapsulating all interactions with the OpenCode runtime. Like that winter night, the bamboo outside the window remained the same as yesterday, lacking the response to her—she still liked looking out the window—runtime is the same, needing someone to silently guard it.

4. Session Persistence Layer

Using SQLite database (opencode-session-bindings-v2.db) to persist the mapping of CessionId to OpenCode SessionId. This design is critical, supporting session recovery and restart, avoiding creating new sessions each time. After all, memory—sometimes forgetting is better, but in the program world, having no memory really doesn't work.

5. Error Recovery Layer

ProviderErrorAutoRetryCoordinator provides automatic retry mechanism,配合 OpenCodeRetryableTerminalFailureClassifier to classify errors—which can be retried, which should fail directly. This layer greatly improves system robustness. Actually nothing much, just letting the system be like a person—fall down and get up again.

Key Data Flow

When an AI request comes in, the data flow goes like this:

Request first reaches OpenCodeCliProvider
Provider requests runtime from OpenCodeRuntimeCoordinator
Coordinator checks if there's an available runtime, if not starts a new one
Query or create session binding through CessionId
Use bound SessionId to call OpenCode API
If error occurs, decide whether to retry based on error type

This process looks simple, but every step has had pitfalls. Does this have meaning? Perhaps, but we've stepped in them all... Also figured it out, stepping in pits is itself part of growth.

Key Design Decisions

From Standalone Process to Shared Runtime

The initial opencode-csharp-sdk proposal adopted a "standalone process per session" model. The idea was beautiful: good isolation, one process crash doesn't affect other sessions. But reality is cruel:

High resource overhead: each process needs to load runtime, memory usage rises straight up
Slow startup: frequent creation and destruction of processes, overhead can't be ignored
Complex management: process lifecycle management is itself a troublesome matter

Ultimately we changed to "system-level shared runtime" mode. All sessions reuse the same runtime process, distinguishing different sessions through session id. This change reduced resource usage by an order of magnitude and significantly improved response speed. Actually nothing much, just changing "one person enjoying alone" to "everyone using together."

Self-Managed Endpoint vs External BaseUri

Early on we encountered a weird 400 BadRequest problem. Investigation revealed it was because we reused an external BaseUrl but lacked necessary context information. OpenCode's runtime is stateful—directly using an external endpoint is equivalent to context loss—like a person without memory, at a loss.

The solution is simple: maintain self-managed runtime, don't depend on external endpoints. Leave BaseUri empty in configuration file, let the system manage runtime lifecycle itself.

AI:
  OpenCode:
    Enabled: true
    ExecutablePath: "opencode"
    BaseUri: null  # Leave empty, use self-managed runtime
    Model: "anthropic/claude-sonnet-4-20250514"

This configuration change looks inconspicuous, but solved the most headache-inducing problem at the time. After all, sometimes the answer is right before our eyes, we just took too many detours.

Session Binding Strategy

Session binding is another key design. We use CessionId as binding key, supporting three modes:

started: New session, create new OpenCode SessionId
resumed: Resume existing session, read binding from database
restarted: Restart session, create new SessionId but preserve history

This design makes session management very flexible—users can resume previous conversations at any time, and the system can automatically rebuild bindings after runtime restart. After all, memory—sometimes want to forget but can't, sometimes want to remember but can't... Memory in the program world is quite reliable.

Implementation Plan

1. Repository Integration

repositories:
  - path: "repos/opencode"
    url: "https://github.com/anomalyco/opencode.git"
    displayName: "OpenCode"
    icon: "⌨️"

Then run the clone script:

node scripts/clone-repos.mjs

This pulls the OpenCode source code locally, and it can be updated at any time later. Actually quite simple, as long as there are no errors...

2. Provider Configuration

Configure OpenCode provider in appsettings.yml:

AI:
  OpenCode:
    Enabled: true
    ExecutablePath: "opencode"
    BaseUri: null
    Model: "anthropic/claude-sonnet-4-20250514"
    RequestTimeoutSeconds: 300
    StartupTimeoutSeconds: 60

Several key parameters:

RequestTimeoutSeconds: Timeout for single request, default 5 minutes—after all, waiting too long is quite torturous
StartupTimeoutSeconds: Runtime startup timeout, giving a full 1 minute

3. Provider Restoration

Bring OpenCode back into the AI Provider system:

Restore OpenCodeCli in AIProviderType enum
Restore creation logic in AIProviderFactory
ExecutorGrainFactory routes OpenCodeCli to dedicated grain

These changes make OpenCode an equally-treated AI Provider, not a special case. Actually everyone is the same, nothing special or not special.

4. Runtime Management Code Example

// Get runtime through OpenCodeRuntimeCoordinator
var runtime = await _runtimeCoordinator.GetRuntimeAsync(
    _settings,
    request.WorkingDirectory,
    cancellationToken);

// Create or resume session
var session = await ResolveSessionAsync(runtime, request, cancellationToken);

// Send prompt
var response = await session.Runtime.Client.PromptAsync(
    session.SessionId,
    promptRequest,
    cancellationToken);

This code looks very concise, but behind it does a lot of work: runtime startup, health checks, session binding query and creation. Like many things,表面上看不出什么，behind it all are stories.

5. Error Recovery Mechanism

// Detect retryable errors and rebuild runtime
if (ShouldRetryWithFreshRuntime(ex, cancellationToken))
{
    await _runtimeCoordinator.InvalidateAsync(runtime, ...);
    var recoveredRuntime = await ResolveRuntimeAsync(request, cancellationToken);
    // Retry with new runtime
}

Automatic retry mechanism greatly improves system robustness—network jitter, runtime occasional crashes can all automatically recover. Actually life is the same, fall down and get up, nothing big... Programs are much stronger than people.

Practice Guide

Key Configuration Quick Reference

Configuration	Default	Description
`Enabled`	`true`	Whether to enable OpenCode provider
`ExecutablePath`	`"opencode"`	OpenCode executable path
`BaseUri`	`null`	External endpoint (recommended to leave empty)
`Model`	-	Default model
`RequestTimeoutSeconds`	`300`	Request timeout
`StartupTimeoutSeconds`	`60`	Runtime startup timeout

Session Binding Database Structure

CREATE TABLE IF NOT EXISTS OpenCodeSessionBindings (
    BindingKey TEXT NOT NULL PRIMARY KEY,
    OpenCodeSessionId TEXT NOT NULL,
    CreatedAtUtc TEXT NOT NULL,
    UpdatedAtUtc TEXT NOT NULL
);

Bindings are retained for 30 days, automatically cleaned after expiration. This design both ensures session recovery capability and avoids unlimited data growth. After all, everything has an expiration, expired then clean up, it's also a form of letting go...

Common Issues and Solutions

1. 400 BadRequest Error

Check BaseUri configuration, recommend leaving empty to use self-managed runtime. If must use external endpoint, ensure context is complete. Actually most times, the problem lies in "taking for granted."

2. Session Cannot Resume

Confirm whether CessionId is correctly passed, check if corresponding binding record exists in database. Like searching for memory, there must be clues.

3. Model Selection Issue

Supports two formats: provider/model (like anthropic/claude-sonnet-4) and no-provider format (like claude-sonnet-4). All roads lead to Rome, just some roads are easier to walk, some roads slightly more winding.

4. Tool Name Mismatch

Tool names are automatically normalized, removing content after parentheses and colons. For example read(path) becomes read, pay attention when calling. These details aren't much, just easily overlooked.

5. Auto Retry Not Working

Check if error classifier correctly identifies retryable errors. By default, network errors, runtime failures etc. automatically retry up to 3 times. After all, trying a few more times doesn't hurt, might just work.

Related Code Paths

Provider: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/OpenCodeCliProvider.cs
Runtime Coordinator: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/OpenCodeRuntimeCoordinator.cs
Configuration: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Configuration/OpenCodeSettings.cs
Proposal Archive: openspec/changes/archive/2026-03-*opencode*/

Summary

HagiCode's process of integrating OpenCode is actually a continuous process of stepping in pits and optimizing. From the initial standalone process mode to shared runtime, from reusing external endpoints to self-managed runtime, every architecture adjustment is driven by actual needs. Actually nothing much, just didn't miss any pit that should be stepped in.

There are three core experiences:

Resource sharing is important: Don't blindly pursue isolation, shared runtime can significantly reduce resource overhead—sometimes one person enjoying alone isn't as good as everyone using together
Be careful with state management: Stateful services should be self-managed, don't depend on external endpoints—after all, your own affairs are best done yourself
Error recovery is essential: Automatic retry mechanism can take system robustness up a level—fall down and get up, nothing big

This solution now runs stably in HagiCode, supporting session recovery, automatic retry, runtime rebuild and other functions. If your project also needs to integrate OpenCode, hope these experiences can help you walk fewer detours. After all... only after walking detours do you know where the shortcut is, sometimes knowing it is of no use.

References

OpenCode GitHub Repository
HagiCode GitHub Repository
HagiCode Official Site: hagicode.com
HagiCode Installation Guide: docs.hagicode.com/installation/docker-compose
HagiCode Desktop: hagicode.com/desktop/
Official Version Demo Video: www.bilibili.com/video/BV1z4oWB3EpY/

Steamworks Multilingual Metadata Management: From Manual Maintenance to Structured Workflow

Hagicode — Sat, 09 May 2026 09:00:07 +0000

Steamworks Multilingual Metadata Management: From Manual Maintenance to Structured Workflow

The Steam platform requires games to provide store descriptions in 28 languages. Traditional manual maintenance is inefficient and error-prone. This article introduces how to build a structured multilingual metadata management system through HagiCode, achieving an integrated workflow from content creation to export and release.

Background

The Steam platform requires games and applications to provide multilingual store descriptions, including fields like about (detailed description) and short_description (short description). For products released globally, localization content in 28 languages is typically required.

This sounds like a simple content management task, but when you actually start working on it, you discover there are more problems than you imagined.

First, the maintenance workload is enormous. 28 languages multiplied by 2 fields equals 56 content blocks that need to be managed. Manually switching languages for editing in the Steamworks website backend is indeed inefficient. Every content update requires repeating this process—it's painful to even talk about it.

Second, scattered content is difficult to manage. Multilingual content is typically scattered across different tools and documents, lacking a unified local storage format. Version control becomes difficult, and team collaboration is prone to errors. After all, scattered things are like scattered memories—when you want to find them, you can't.

Furthermore, DLC content and main application content management are siloed. If your game has multiple DLCs, each DLC needs to maintain multilingual content separately, and management complexity grows exponentially. It's like life—things pile up, and you don't know where to start cleaning up.

Finally, the export format is unintuitive. The JSON format required by Steamworks doesn't match human reading habits, making manual editing error-prone. After all, who wants to look at that dense JSON?

These were all problems we encountered during the actual development of the HagiCode project. As an AI coding tool for global development, we need to maintain complete multilingual content for the Steam platform. Traditional maintenance methods could no longer meet our needs, and we urgently needed a more efficient solution. Actually, there's no other way—we had to build it ourselves.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI coding tool that supports multiple AI providers and code editors. During development, we needed to maintain multilingual store content for the Steam platform, which drove us to build a structured metadata management system.

The multilingual metadata management solution shared in this article is exactly what we actually refined through trial and optimization during HagiCode development. If you find this solution valuable, it shows our engineering strength is pretty good—so HagiCode itself is worth paying attention to. After all, a tool that can solve problems is a good tool, right?

Core Concepts

Languages and Fields

Steamworks supports a fairly complete list of languages, covering major markets:

en-US, fr-FR, it-IT, de-DE, es-ES,
bg-BG, cs-CZ, da-DK, nl-NL, fi-FI,
el-GR, hu-HU, id-ID, ja-JP, ko-KR,
nb-NO, pl-PL, pt-BR, pt-PT, ro-RO,
ru-RU, zh-CN, es-419, sv-SE, th-TH,
zh-TW, tr-TR, uk-UA, vi-VN

The most commonly used are en-US (English), zh-CN (Simplified Chinese), zh-TW (Traditional Chinese), ja-JP (Japanese), and ko-KR (Korean). After all, these languages cover major markets—once you get these done, the others aren't so scary.

The main fields that need to be maintained include two:

about: Detailed description, supports rich text format
short_description: Short description, with a 300-character limit

Scope Concept

Steam app content can be divided into two scopes:

Base App: Main application content
DLC: Downloadable content, each DLC has independent content management

This distinction is important because DLCs typically need independent store descriptions, and a game may have multiple DLCs that need unified management. It's like life—some things are primary, some are additional, but they all need to be managed properly, or things become a mess.

Data Model Design

The system defines a clear data model to support multilingual content management:

// 28 supported language codes
const STEAMWORKS_SUPPORTED_LOCALES = [
  'en-US', 'fr-FR', 'it-IT', 'de-DE', 'es-ES',
  'bg-BG', 'cs-CZ', 'da-DK', 'nl-NL', 'fi-FI',
  'el-GR', 'hu-HU', 'id-ID', 'ja-JP', 'ko-KR',
  'nb-NO', 'pl-PL', 'pt-BR', 'pt-PT', 'ro-RO',
  'ru-RU', 'zh-CN', 'es-419', 'sv-SE', 'th-TH',
  'zh-TW', 'tr-TR', 'uk-UA', 'vi-VN'
];

// Supported fields
const STEAMWORKS_SUPPORTED_FIELDS = [
  'about',           // Detailed description
  'short_description' // Short description
];

// Content scope
type SteamworksScopeKind = 'base' | 'dlc';

There are a few considerations in this model design—well, actually, it's just about making things a bit simpler:

Use standard language code formats (like zh-CN instead of chinese)—after all, standard things are always more reliable
Explicitly list field types for future extension—who knows if more fields will be needed later
Distinguish scope types to support unified management of Base App and DLC—it's always good to keep things clear

File Storage Structure

Content is stored in .hagiclaw-data/steamworks-metadata/ in the project directory, using a hierarchical directory structure:

.hagiclaw-data/
└── steamworks-metadata/
    └── default-app/
        ├── workspace.json              # Workspace configuration manifest
        ├── base/                       # Base application content
        │   ├── en-US/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   ├── zh-CN/
        │   │   ├── about.md
        │   │   └── short_description.md
        │   └── ...
        └── dlc/                        # DLC content
            └── turbo-engine/
                ├── en-US/
                │   ├── about.md
                │   └── short_description.md
                └── ...

This structure design has several advantages—or at least, it's much better than the previous approach:

Human-readable: Each content is an independent Markdown file that can be edited directly—after all, human eyes prefer to see things clearly
Version control friendly: Text files make it easy to track change history and compare differences—so what was changed is clear at a glance
Strong extensibility: Adding new languages or fields only requires creating new files—like building blocks, add whatever you want
Clear structure: The directory structure intuitively reflects how content is organized—won't make people feel confused

workspace.json stores workspace configuration, including DLC list and language configuration information. After all, some things still need a manifest—otherwise, after a while, who remembers what they put where.

Markdown to BBCode Conversion

Steam uses BBCode format for rich text, not standard Markdown. This brings additional workload to content creation—either write BBCode directly or manually convert it later.

HagiCode's solution is: let developers create content in familiar Markdown, and the system automatically converts it to Steam BBCode. After all, people are always accustomed to what they're familiar with—why force yourself to adapt to those strange curly braces?

Conversion Rules

// Heading conversion
# HagiCode        → [h1]HagiCode[/h1]
## Features        → [h2]Features[/h2]

// Text styles
**bold text**     → [b]bold text[/b]
*italic text*     → [i]italic text[/i]
`code`            → [code]code[/code]

// Links and images
[text](url)       → [url=url]text[/url]
![alt](src)       → [img src="{STEAM_APP_IMAGE}/extras/..."][/img]

// Lists
- item 1
- item 2          → [*]item 1
                   [*]item 2
                   (wrapped in [list])

Language Wrapping

When exporting, content needs to be wrapped with language tags:

wrapWithSteamLanguage(locale: SteamworksLocaleCode, bbcode: string): string {
  // Returns [lang=english]...[/lang] format
}

Language codes need to be mapped to Steam's format:

en-US → english
zh-CN → schinese
zh-TW → tchinese
ja-JP → japanese
ko-KR → korean

This mapping relationship isn't actually that complicated, it just needs to be remembered. After all, every platform has its own rules, we can only adapt.

Export Format

The exported JSON needs to meet Steamworks' structure requirements:

{
  "itemid": "1158573",
  "languages": {
    "english": {
      "app[content][about]": "[h1]HagiCode[/h1]\n[b]About[/b]...",
      "app[content][short_description]": "AI coding tool..."
    },
    "schinese": {
      "app[content][about]": "[h1]HagiCode[/h1]\n[b]关于[/b]...",
      "app[content][short_description]": "AI 编码工具..."
    }
  }
}

The key points aren't many, just need to remember these format requirements:

itemid corresponds to Steam AppID
Steam's language codes (like schinese) are used under languages
Field paths use app[content][fieldName] format
Values are converted BBCode strings

These rules seem a bit tedious, but you get used to them. After all, every platform has its own temperament, we can only adapt.

API Service Design

The system provides a complete REST API to support the multilingual content management workflow:

Load Workspace

GET /api/steamworks/metadata

Returns workspace configuration, all languages, and field content. After all, there needs to be a place to pull everything out for viewing.

Save Content

POST /api/steamworks/metadata

{
  "scopeId": "base-app",
  "scopeKind": "base",
  "values": {
    "en-US": {
      "about": "Markdown content...",
      "short_description": "Short text..."
    },
    "zh-CN": {
      "about": "Markdown 内容...",
      "short_description": "简短文本..."
    }
  }
}

When saving, the system writes Markdown content to corresponding .md files. This way nothing gets lost—after all, memory is always unreliable.

Render Preview

POST /api/steamworks/metadata/preview

{
  "locale": "zh-CN",
  "field": "about",
  "content": "# HagiCode\n\n这是关于..."
}

Returns Markdown rendering result and BBCode conversion result for easy previewing. Preview is like looking in a mirror—you should at least see what you look like before going out.

Export JSON

POST /api/steamworks/metadata/export

{
  "scopeId": "base-app",
  "scopeKind": "base"
}

Generates Steamworks-format JSON that can be directly imported into the Steamworks backend. This step is essentially packaging everything up, ready for shipping.

DLC Management

POST /api/steamworks/metadata/dlc    // Create
PUT /api/steamworks/metadata/dlc     // Update
DELETE /api/steamworks/metadata/dlc  // Delete

DLC management includes creating, updating, and deleting DLC metadata configurations. After all, DLC is also content and needs to be managed properly.

Usage Workflow

1. Access Metadata Panel

Open the Steamworks Metadata panel in the HagicLaw workspace, and the system will load the current workspace's configuration and content. Once all preparations are done, you can begin.

2. Select Edit Scope

Select Base App or a specific DLC in the left navigation. Each scope independently manages its multilingual content. Like organizing a room—first categorize things, then clean them up one by one.

3. Multilingual Matrix Editing

Expand the languages you need to edit, and directly edit the Markdown content for about and short_description. The system supports:

Real-time Markdown rendering preview
Steam BBCode conversion preview
Character count and length checking

These preview features are actually quite useful—at least you can know what your content looks like. After all, no one wants to write a bunch of stuff only to find the format is completely wrong.

4. Save Content

Click the save button, and content is automatically written to corresponding .md files. Files are included in Git version control for easy change tracking. Saving is like writing down memories—they won't be forgotten even after a long time.

5. Validation Checks

The system automatically checks:

Whether required fields are complete
Whether short_description exceeds 300 characters
Whether Markdown syntax is correct

These checks can avoid some basic errors—after all, humans make mistakes, it's always good to have a machine help watch over things.

6. Export JSON

Select the scope to export (Base App or specific DLC), and the system generates Steamworks JSON containing all languages. Copy the JSON and paste it into the Steamworks backend to complete the import. Once this step is done, the entire workflow is complete. Everything is ready, just waiting for release.

Notes

Language Code Mapping

The system's en-US corresponds to Steam's english, and zh-CN corresponds to schinese. This mapping is handled automatically during export, but needs attention when manually editing JSON. After all, some things machines can help you with, but some you still need to remember yourself.

BBCode Limitations

Steam only supports a subset of BBCode, and complex Markdown may not convert perfectly. It's recommended to check conversion results in preview. Preview is like looking in a mirror—check what you look like before going out.

Image Paths

Images are converted to [img src="{STEAM_APP_IMAGE}/extras/..."] placeholder format. Actual images need to be uploaded separately to the Steam backend. Images are sometimes more persuasive than text, just a bit more troublesome to upload.

Field Validation

short_description has a strict 300-character limit. The system validates before export, but it's recommended to control length during editing. After all, writing too many characters is useless—the platform only looks at the first 300, so you have to be concise.

Version Control

All Markdown files can be included in Git version control for easy change history tracking and collaborative editing. It's recommended to commit changes regularly. Version control is like a time machine that lets you return to a past moment and see what you wrote then.

DLC Management

DLC's itemId needs to correspond to the DLC AppID in the Steamworks backend. When creating a DLC, ensure the ID is accurate. IDs are hard to change once wrong, so it's better to be careful.

Summary

The core challenge of Steamworks multilingual metadata management lies in how to efficiently maintain large amounts of multilingual content. Through structured data models, human-friendly file storage, and automated conversion/export workflows, we can transform this tedious process into a manageable content creation workflow.

This solution has proven effective in the practice of the HagiCode project. We transformed from a manual, error-prone state to a structured, verifiable, collaborative workflow. This not only improved efficiency but also reduced human error. After all, when the tool is well-made, things become simple.

If you're developing applications for the Steam platform and need to maintain multilingual content, I hope this solution can provide some inspiration. Multilingual content management doesn't have to be a painful thing—with the right tools and workflows, it can become relatively easy. Or at least, not so despair-inducing...

References

Steamworks Documentation - Store Metadata
Steam BBCode Guide
HagiCode project: github.com/HagiCode-org/site
HagiCode official site: hagicode.com

If this article helped you:

Give a Star on GitHub: github.com/HagiCode-org/site
Visit the official site to learn more: hagicode.com
Watch the official demo video: www.bilibili.com/video/BV1z4oWB3EpY/
One-click installation experience: docs.hagicode.com/installation/docker-compose
Desktop quick installation: hagicode.com/desktop/

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-05-09-steamworks-multilingual-metadata-management%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Quantifying AI Cost-Benefit Analysis

Hagicode — Sat, 09 May 2026 02:20:13 +0000

Quantifying AI Cost-Benefit Analysis

Your boss asks: "How much does it cost to equip employees with AI assistants, and is it worth it?" You can't answer, and you feel unsure. This article discusses how to calculate this clearly.

Background

In recent years, Claude Code, GitHub Copilot, and various AI programming assistants have flooded in like a tidal wave. As a technical person, you've probably already started using them and feel genuinely more efficient—like someone handing you a ladder when you need to climb.

But when it comes to discussing ROI with your boss or clients, you often hit a wall—how do you quantify that subjective feeling of "increased efficiency"? I understand this feeling. It's like when someone asks you "what do you like about her?" and you stutter for a while, only saying "I just do." That's fine, but bosses want numbers, not your feelings.

And that's not the only problem:

ROI: Is the cost of equipping the team with AI tools worth it?

Efficiency Quantification: How do we translate "productivity gains" across different roles and usage levels into measurable metrics?

Risk Assessment: If competitors大规模 adopt AI, how much will our competitiveness suffer?

Traditional ROI calculations often overlook two critical factors:

Enterprise Total Cost Perspective: Only considering salary while ignoring city differences, social insurance, housing fund, and other additional costs
Token Economics Model: Lack of a calculation framework connecting AI usage (Tokens) to actual output

Both factors are indispensable. Here's a real example: For the same 300k annual salary, the actual cost to the enterprise in Beijing versus Wuhan can differ by over 30%. And that's not even counting the cost of AI usage itself. Cost is like an iceberg—you only ever see the tip...

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project.

HagiCode is essentially just an AI code assistant project. However, during development, we genuinely needed to accurately assess the cost-effectiveness of different AI models—after all, money doesn't grow on trees. To that end, we built a complete calculation framework and open-sourced the HagiCode Cost assessment tool.

If you're also thinking about AI cost issues, this approach might give you some reference. Or maybe not—I can't guarantee that, but we're just giving it a try.

Core Calculation Framework

A complete AI cost-benefit assessment requires establishing a three-layer model:

Input Layer
├── Annual salary data
├── City tier coefficient
├── AI model selection
├── Efficiency multiplier estimate
└── Daily Token usage

Calculation Layer
├── Enterprise total cost accounting
├── AI annual cost calculation
├── Cost proportion analysis
├── ROI calculation
└── Equivalent workforce conversion

Output Layer
├── AI cost proportion
├── Efficiency gain
├── Return on investment
├── Equivalent workforce count
└── Elimination risk assessment

This framework looks complex enough to make your head spin. Actually, the core logic is quite simple: calculate the enterprise's real labor costs clearly, calculate the AI's annual costs clearly, then look at the ROI and equivalent workforce. After all, simplifying complexity is the right path.

Calculating Key Metrics

Enterprise Annual Total Labor Cost

First, enterprise total cost—this isn't simply annual salary multiplied by 12 months. Real costs need to consider two factors:

City Coefficient: Additional costs in first-tier cities (Beijing, Shanghai, Guangzhou, Shenzhen) are about 30% higher than other cities. This includes social insurance, housing fund, various benefits, and the cost-of-living premium for first-tier cities—after all, the price of living in Beijing versus Wuhan is indeed different.

Additional Employment Costs: Roughly equivalent to 1 month's salary, covering year-end bonuses, various subsidies, office equipment amortization, etc. These amounts may seem small individually, but they add up.

So the formula is:

enterpriseAnnualTotalLaborCost = annualSalary × (1 + cityCoefficient) + annualSalary/12

City coefficient can refer to this standard:

First-tier cities (Beijing, Shanghai, Guangzhou, Shenzhen): 0.4
New first-tier (Hangzhou, Chengdu, Suzhou, Nanjing): 0.3
Second-tier cities (Wuhan, Xi'an, Tianjin, Zhengzhou): 0.2
Other cities: 0.1

AI Annual Cost

AI cost calculation is slightly more complex because AI models charge by Token. And input and output prices differ—output is typically 5-10x more expensive than input. This isn't surprising, after all, output is the AI "working," while input is just you "talking."

In code scenarios, the input-output ratio is about 3:1, so we can calculate a composite unit price:

// Composite unit price (based on 3:1 input-output ratio)
compositeUnitPrice = (3 × inputPrice + outputPrice) / 4

// Daily cost
dailyAICost = dailyTokenUsage(M) × compositeUnitPrice

// Annual cost (based on 264 working days)
annualAICost = dailyAICost × 264

For example, GPT-5.4's input price is 2.5 USD/1M Token, output price is 15 USD/1M Token. Then the composite unit price is:

compositeUnitPrice = (3 × 2.5 + 15) / 4 = 5.625 USD/1M Token

Converting to RMB (assuming 1 USD = 7.25 CNY):

compositeUnitPrice = 5.625 × 7.25 = 40.78 yuan/1M Token

Exchange rates fluctuate, but we fix them for calculation convenience.

Core Benefit Metrics

With the two costs above, we can calculate core metrics:

// AI cost proportion
aiCostProportion = annualAICost / enterpriseAnnualTotalLaborCost

// Efficiency gain
efficiencyGain = efficiencyMultiplier - 1

// AI return on investment
aiROI = efficiencyGain / aiCostProportion

// Affordable workflow count
affordableCount = enterpriseAnnualTotalLaborCost / annualAICost

// Equivalent workforce
equivalentWorkforce = 1 + (efficiencyMultiplier - 1) × min(affordableCount, 1)

Meanings of these metrics:

AI Cost Proportion: The percentage of enterprise labor costs consumed to maintain Agent workflows. The lower this number, the more "cost-effective" the AI usage. Who doesn't like saving money?

Return on Investment: Efficiency gain ÷ AI cost proportion. Less than 1 means "somewhat wasteful," greater than 2 means "very worthwhile." This is easy to understand—like spending money to buy time, you calculate whether it's worth it.

Equivalent Workforce: There's a point easily misunderstood here. It's not directly accepting the efficiency multiplier, but whether the enterprise can afford this AI workflow. If affordableCount is less than 1, then equivalent workforce won't reach your expected efficiency multiplier. After all, even the cleverest housewife can't cook without rice...

Practical Calculation Example

Let's do a real accounting example. Assume a first-tier city backend developer:

Annual salary: 300k
Using GPT-5.4, efficiency multiplier: 2.5x
Daily Token usage: 12 M

Step 1: Calculate enterprise total cost

enterpriseTotalCost = 30 × (1 + 0.4) + 30/12 = 44.5k

Step 2: Calculate AI annual cost

compositeUnitPrice = 40.78 yuan/1M Token
dailyCost = 12 × 40.78 = 489.36 yuan
annualCost = 489.36 × 264 = 129,191 yuan ≈ 12.9k

Step 3: Calculate benefit metrics

AI cost proportion = 12.9 / 44.5 = 29%
efficiencyGain = 2.5 - 1 = 150%
return on investment = 1.5 / 0.29 = 5.17x

Step 4: Calculate equivalent workforce

affordableCount = 44.5 / 12.9 = 3.45
equivalentWorkforce = 1 + (2.5 - 1) × 1 = 2.5 people

What's the conclusion? This AI usage has an ROI over 5, falling in the "very worthwhile" range. If the entire team uses it, forming approximately 2.5 people's production capacity advantage, it would be very competitive in the market.

This makes sense—after all, the money you spend on AI is far less than your additional output. This deal is worth it.

Impact of Multi-Agent

HagiCode discovered an interesting phenomenon in actual use: a single Agent's efficiency gains have an upper limit.

This is actually quite natural—no matter how capable a person is, they can only do one thing at a time. After all, you're not an octopus.

Traditional single Agent usage patterns have several bottlenecks:

Serial Limitation: Proposal → Implementation → Review → Fix must wait sequentially. No matter how fast a single Agent is, it can only do one thing at a time. It's like cooking—you can only wash, cut, and stir-fry step by step.

Quota Waste: Monthly quota limits can't be fully utilized. Unused quota this month doesn't roll over to next month. This isn't surprising, just a bit wasteful.

Context Switching: Different tasks require repeatedly establishing context, meaning you have to explain background information each time. Like chatting with different people about the same thing—starting from scratch each time gets tiring.

HagiCode's multi-Agent architecture solves these problems through parallel sessions:

Parallel 10x+: Multiple Agents drive multiple instances simultaneously, achieving true parallel work
Throughput Increase: Proposal, implementation, and fixes can advance in parallel without waiting for each other
Improved Token Utilization: OpenSpec process reduces rework, spreading equivalent consumption

The change this brings is enormous. Using the previous example, if using HagiCode multi-Agent architecture:

Parallel sessions: 4
Token utilization improvement: 1.5x

Amplified calculation:

amplifiedEfficiency = 2.5 × 4 = 10x
optimizedDailyToken = (12 × 4) / 1.5 = 32 M
optimizedAnnualCost = 32 × 40.78 × 264 = 344k

New benefit metrics:

newAICostProportion = 34.4 / 44.5 = 77%
newROI = 9 / 0.77 = 11.68x
newEquivalentWorkforce = 1 + (10 - 1) × 1 = 10 people

Although AI cost proportion rose from 29% to 77%, ROI increased from 5.17x to 11.68x, and equivalent workforce changed from 2.5 to 10 people.

This is the power of multi-Agent parallelism. One Agent is one person; ten Agents are a team... The difference isn't just a little bit.

Practical Considerations

Don't Get City Coefficient Wrong

Employment cost differences across cities are significant—first-tier cities' additional costs are about 30% higher than other cities. When calculating, be sure to use the correct city tier. A small difference in this number can significantly skew the final result. After all, "a miss is as good as a mile"... This is an old saying, but it still holds true.

Input-Output Ratio Isn't Fixed

Code scenarios default to a 3:1 input-output ratio, matching the proportion of prompts to generated code in actual programming. But if you're doing other types of work—like writing copy or doing data analysis—this ratio might be completely different.

This is normal—different work, different methods.

Efficiency Multiplier Is Subjective

Efficiency multiplier is a subjective estimate. It's recommended to combine with actual observation:

1.5-2x: Familiar with basic functions, occasional use
2-3x: Proficient, daily high-frequency use
3x+: Deep integration, forming专属 workflows

Don't estimate too high initially—observe for a while before adjusting. After all, higher expectations lead to greater disappointment.

How to Calculate Token Usage

If you don't know your daily Token usage, you can estimate this way:

Check platform usage statistics (both Claude and OpenAI have them)
Record Token consumption from several typical conversations and take an average
Multiply by your daily conversation count

Or just use HagiCode Cost to calculate—it has reference values for common scenarios. This is convenient and saves you from blind trial and error.

Impact of Exchange Rate Fluctuations

USD models require exchange rate conversion, but rates fluctuate. Calculators typically use fixed rates (like 1 USD = 7.25 CNY), while actual costs may vary with exchange rate fluctuations. This error is usually small, but keep it in mind.

After all, everything has an approximation—precision to several decimal places isn't really necessary...

Technical Implementation Points

If you want to implement this calculation logic yourself, several technical details are worth noting:

Multi-Currency Support

function convertCnyAmountToCurrency(
  amountCny: number,
  targetCurrency: "USD" | "CNY"
): number {
  if (targetCurrency === "CNY") return amountCny
  return amountCny / EXCHANGE_RATE_USD_TO_CNY
}

There's not much to say about this code—it's just simple currency conversion.

Multi-Language Localization

function getLocalizedModelCopy(
  model: ModelPricing,
  language: SupportedLanguage
): LocalizedModelMeta {
  return {
    description: language === "zh-CN"
      ? model.description
      : model.descriptionEn,
    pricingContext: language === "zh-CN"
      ? model.pricingContext
      : model.pricingContextEn,
    // ... other fields
  }
}

Multi-language support is complex in some ways, simple in others. It's essentially storing different language content and retrieving it when needed.

Regional Differentiation

function getCityTierLabel(
  cityTier: CityTier,
  region: "cn-mainland" | "international",
  language: SupportedLanguage
): string {
  const city = benchmarkData.cityCoefficients.find(
    item => item.tier === cityTier
  )

  if (region === "cn-mainland") {
    return language === "zh-CN" ? city.label : city.labelEn
  }

  return language === "zh-CN"
    ? city.internationalLabel
    : city.internationalLabelEn
}

Regional differentiation means displaying different labels for different regions. This isn't difficult—just judge the region and language, then return the corresponding value.

Summary

AI cost-benefit assessment isn't anything profound—the core is three calculations: enterprise labor costs, AI usage costs, and efficiency improvement magnitude. Calculate these three clearly, and the ROI naturally emerges.

This is like many things in life—seemingly complex, but when broken down, it's just that. Few people are willing to sit down and calculate it.

But there's an easily overlooked point here: the multiplier effect from multi-Agent architecture. No matter how strong a single Agent is, it can only improve efficiency linearly. But multiple Agents working in parallel bring exponential capacity improvements. This is the core reason HagiCode chose a multi-Agent architecture.

One person's power is limited; a group's power is infinite. This sounds like a platitude, but applied to AI, it's fitting.

If you're also thinking about AI cost issues, welcome to try HagiCode Cost to experience our calculator. Or go directly to GitHub to see the source code—maybe it'll give you some inspiration.

Or maybe not—I can't guarantee that. Just giving it a try, after all, paths are made by walking...

Writing this, I suddenly remembered an old saying: "To do good work, one must first sharpen one's tools."

But sometimes, even with sharp tools, knowing how to use them is another matter. AI is like a double-edged sword—used well, it's assistance; used poorly, it's a burden. The balance is for you to find.

Enough of that. Hope this helps you.

DEV Community: Hagicode

Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice

Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice

Background

About HagiCode

Analysis

1.x Cut Startup Parameters to Just One

ReasonixOptions Fields Still There, But Semantics Changed

How DeepSeek V4 Gets In

Working Directory and Session Recovery Go Through ACP, Not CLI Flags

Solution

Step 1: Install Reasonix CLI

Step 2: Configure DeepSeek V4 Credentials in reasonix.toml

Step 3: Configure HagiCode's ProviderConfiguration

Step 4: Use Console for End-to-End Verification

Practice

How to Fill the Hero Configuration Form in Frontend

Session Binding and Recovery

Monitoring and Degradation

Several Practical Points to Note

A Minimal Verification Path

Summary

References

Summary

Original Article & License

Pi Agent Integration: Message Parsing, Retry, and Cancellation

Pi Agent Integration: Message Parsing, Retry, and Cancellation

Background

About HagiCode

Overall Layering

Message Parsing: Converting Pi's Private Events to Shared Messages

Technique One: Converting Cumulative Snapshot to Delta

Technique Two: Buffer Thinking Until Turn End

Fault Tolerance: Bad Lines Can't Crash the Stream

Retry: If Provider Layer Doesn't Do It, Who Does?

Why No Automatic Retry

What Does This Mean for PiProvider

What If You Want to Retry

Cancellation: Token Pass-through + Three-stage Shutdown

Full-chain Pass-through

Three-stage Progressive Shutdown

PiProvider's Exception Cleanup

Unified Contract for Startup Failures

Practice: Correct Way to Consume Streams

Common Pitfalls Quick Reference

How to Verify

Summary

Summary

Original Article & License

How to Use Upptime to Build Your Own Status Page for Free

How to Use Upptime to Build Your Own Status Page for Free

Background

About HagiCode

Analysis: How Upptime Actually Works

Data Flow: One Configuration File Drives Everything

The Division of Six Workflows

Data Persistence: Files as Database

Events and Notifications: Issues as Event Log

Solution: Five Steps to Replicate a Status Page

Step 1: Create Repository from Template

Step 2: Edit .upptimerc.yml

Step 3: Configure Secrets and Permissions

Step 4: Enable GitHub Pages

Step 5: Verification and Maintenance

Practice: I've Walked Through the Potholes for You

Practice 1: Monitoring Granularity Selection

Practice 2: Clever Use of Response Time Badges

Practice 3: Repository Size Control

Practice 4: Real Usage of Maintenance Events

Practice 5: Boundaries Between Template Updates and Customization

Practice 6: Reality Constraints of Free Quotas

Conclusion

References

Summary

Original Article & License

How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission

How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission

Background

About HagiCode

Analysis: Four Critical Questions to Clarify Before Publishing

Step 2: Edit `.upptimerc.yml`

3. Desktop Applications Must Declare `runFullTrust` Capability