DEV Community

Chao Y
Chao Y

Posted on Edited on

Harngine: an execution framework for TypeScript agent applications

I'm building Harngine, a TypeScript execution framework for agent applications. A model can answer a turn or propose a tool call, but an application also needs to decide which calls are allowed, when to wait for a person, how to continue after a restart, and how to explain what ran. Harngine provides the runtime for that work.

An application defines Agents, Workflows, and Tools, then starts Work. Harngine persists the execution and its history. The application still owns its UI, users, domain rules, and definition of success. Model adapters handle provider transport; Tool adapters connect external systems.

The five concepts

Concept What it represents
Agent A reusable definition directed by a model. The application controls the Tools it can see.
Workflow A reusable definition directed by TypeScript code. It makes orchestration and waits explicit.
Tool A typed boundary to an operation. Harngine validates and authorizes a Call before execution.
Work One execution of an objective, with an ID, status, Calls, interactions, result, and inspection history.
Session Optional continuity across several separate Work executions.

An Agent or Workflow defines how a task can run. Work records this particular run. That distinction matters when a process restarts or a developer needs to inspect a decision afterward.

What Harngine handles

Execution and recovery. Work has a stable identity and persisted state. Workflows use named durable operations, so completed steps can be recognized when execution resumes. A task can wait for a timer or a person without losing its place.

Tool boundaries. Tools declare input and output schemas. Harngine validates Calls, checks authority and approval policy, records attempts, and supports cancellation. Model output proposing a Tool does not by itself grant permission to execute it.

Human decisions. A Workflow or Agent can wait for a question or approval. The interaction and its outcome become part of the Work history.

Inspection. Applications can examine context, model responses, decisions, Tool activity, interactions, and results. This gives developers more than a final answer when they need to understand behavior.

Continuity. Sessions can carry conversation across multiple objectives, while each objective remains separate Work. This is useful for an assistant that works with a person over time.

Harngine currently runs as an embedded Node.js runtime backed by SQLite. One application process owns a runtime directory at a time, and active Work needs its original Agent and Tool revisions to continue after a restart. Harngine does not choose the product's UI or business policy. External writes still need an idempotency or reconciliation strategy appropriate to the target system; persisted Work does not make an external effect happen exactly once.

Where it fits

Harngine can support coding assistants, support processes, research tools, and persistent interactive applications. The repository includes examples of different shapes, from a small Workflow to larger applications. They are ways to use the framework, rather than its limits.

Version 0.1.0 is available on npm and requires Node.js 24.21 or later in the 24.x line. The public API may change before v1.

npm install harngine
Enter fullscreen mode Exit fullscreen mode

Start with the source and examples or read the framework guide. The small recovery example shows a typed Tool call and a durable timer without requiring a model account.

For a brief visual introduction, watch the Harngine framework video. It includes two example applications after the framework overview.

I'm interested in the execution problems other builders encounter. Where do your agent applications need more control or visibility: recovery, Tool authority, human approval, or the history of a run?

Top comments (7)

Collapse
 
nazar-boyko profile image
Nazar Boyko •

What happens to a Tool call that was running when the process died? On resume, does Harngine retry it or mark it as unknown and hand the decision to the app or a person?

Collapse
 
chaoyangnz profile image
Chao Y •

Thanks Nzar. good question.
If the process dies during a Tool call, it records the outcome as unknown. It won’t repeat an uncertain write. On restart, the Tool can check what happened; if it can’t tell, the Work waits for a person to resolve it. A retry is possible only after confirming the write did not happen and checking the Tool’s retry rules.
but more strategies can be considered to fit different scenarios

Collapse
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

The Work-versus-definition split is the right abstraction — most frameworks blur 'this run' with 'how it runs' and then can't explain a restart. My one worry: active Work needs its original Agent and Tool revisions to continue, which sounds like version pinning becomes a migration problem fast. How do you handle a tool schema changing mid-flight?

Collapse
 
chaoyangnz profile image
Chao Y •

That’s a real operational cost of exact revisions. Changing a Tool schema creates a new revision, and Harngine won’t silently continue active Work using the new contract.

To finish existing Work, the application needs to keep its original Agent or Workflow and Tool revisions available while directing new Work to the new definitions. If an old revision is removed, its Work remains inspectable but cannot continue through that missing definition.

Harngine 0.1.0 does not automatically migrate active Work between Tool schemas. We need to document the side by side deployment pattern more clearly. Thanks for raising this.

Collapse
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

The side-by-side pattern is honest — refusing to silently continue on a new contract is the right default, even if it costs the operator a migration step. The inspectable-but-not-continuable state is the interesting edge: is that a deliberate dead end to force an explicit decision, or is there a planned migration path for Work stranded on a removed revision?

Thread Thread
 
chaoyangnz profile image
Chao Y •

Thanks for the insights.
It’s a deliberate stop. Registering the exact old definitions again lets that Work continue. So far, moving to new definitions means starting new Work and carrying over any needed state in the application. The engine doesn’t yet migrate active Work in place.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That's an honest trade-off — a clean stop beats a silent half-migration that corrupts the run. The restart cost is real, though: if a long-running Work has to be rebuilt from scratch every time a tool definition moves, the state carry-over becomes the migration problem in disguise. Is in-place migration on the roadmap, or is the deliberate stop the long-term stance?