Skip to main content

Starlight Part 4: Building a Domain Agent with an Explicit Contract

Replace the retired no-code Sentinel editor with a small, reviewable Node.js agent and an outcome verifier.

3 min read
Starlight Part 4: Building a Domain Agent with an Explicit Contract
On this page

Revised for the September 5 platform refinement
These five articles now describe the general-purpose Node.js agent platform. The reviewed main-branch checkout identifies itself as 5.0.0-alpha.2; the wire protocol remains 1.0. The latest GitHub release is still the older v1.3.4. Use the reviewed checkout for these examples, rather than assuming the alpha has been published to a package registry.

The older Part 4 described a visual editor that generated Python Sentinels. That editor is outside the current supported implementation. Today, extending Starlight means registering a domain agent with a small JavaScript contract and, where needed, a verifier.

Keep selection free of side effects

An agent declares its name and capabilities, then uses canHandle(intent) to indicate whether it can attempt a goal. Selection may happen without execution, so this check should not write files, reserve inventory, send messages, or call a paid model. Perform work only inside the execution path.

Make the contract easy to inspect

Contract elementDesign question
nameCan a reviewer identify which implementation ran?
capabilitiesWhat kind of work can the registration perform?
canHandleCan eligibility be evaluated without changing state?
runWhat input is required, and what result or error is returned?
verify (optional)What independent observation supports completion?

Part 1 includes a complete word-counter registration. For a business workflow, use the same pattern but validate input types, resource scope, and constraints before acting. Return a clear failure when the request is outside the agent’s responsibility.

Verify the outcome outside the success message

A report-writing agent should read the file back. An API agent should inspect the returned record or query its final state. A browser agent should assert the resulting application state. Merely repeating the agent’s own “completed” label does not add independent evidence.

The packaged data-report agents provide a concrete implementation to study before designing a custom verifier. Treat their code as the reference for the current hook signature and result shape.

Load local agent modules through the CLI

The CLI supports CommonJS and ESM modules. Inspect the example registrations before running a mission; the agent inventory helps expose unexpected implementations or missing capabilities.

bash
node bin/starlight-platform.js agents --agents examples/data-report/agents.cjs

A domain agent is trusted code

The platform is not a sandbox. Agents run with host permissions, and a browser or model integration can have its own network and data behavior. Review the implementation, restrict its runtime environment, and keep secrets out of mission inputs and output evidence.

  • Start with one capability and a deterministic fixture.
  • Exercise unsupported input and failed verification.
  • Test cooperative cancellation during real work.
  • Use separate ownership or locks for shared mutable resources.
  • Add model planning only where the task actually needs it.

This is a narrower extension story than a no-code marketplace, but it gives each agent a contract that can be read, tested, and maintained.

Continue the series

Reviewed implementation and setup

September refinement changelog

Core protocol specification

Dhiraj Das

About the Author

Dhiraj Das is an Automation Consultant with over a decade of experience building systems that expose failures, reduce flakiness, and make complex workflows repeatable. He applies that discipline to AI-agent validation, LLM testing, and postmortems.

He shares small open source utilities from real automation work, including: waitless (flaky tests), sb-stealth-wrapper (bot detection), selenium-teleport (state persistence), selenium-chatbot-test (AI chatbot testing), lumos-shadowdom (Shadow DOM), and visual-guard (visual regression).

Share this article: