@galaxy-stack/ai-coder-core

@galaxy-stack/ai-coder-core

Provider-neutral, platform-neutral runtime for the Galaxy AI Coder single agent. The same core is intended for:

• galaxy-code v2 — deterministic Node.js CLI laboratory;
• galaxy-vscode-extension — VS Code host adapters;
• galaxy-desktop — Tauri host adapters.

Status

The single-agent runtime, context manager, prompt assembler, tool registry, approval policy, checkpoint format, trace protocol, lexical retrieval, and completion gate are implemented and covered by deterministic tests.

galaxy-code v2 is the reference conformance host. VS Code and Desktop should not copy runtime logic; they should implement the same ports and pass the same host conformance fixtures first.

This package is still pre-integration: only galaxy-code passes the full conformance gate today. Optional MCP, semantic retrieval, background terminal sessions, and subagents are outside the current runtime baseline.

Versioning and release policy

All releases before 1.0.0 are development quality. Every release carries an explicit semver pre-release tag (x.y.z-alpha.N) while the host conformance gate is still running; stable-looking x.y.z numbers are reserved for post-1.0.0 releases. Publish pre-releases with a dist tag (npm publish --tag alpha) so npm install @galaxy-stack/ai-coder-core@latest never upgrades a consumer to an unverified alpha.

Every behavior- or API-level fix lands in CHANGELOG.d as a dated fragment (date, time, area, before/after, regression requirement) and is compiled into CHANGELOG.md at release time. When reading any audit or live run, compare the recorded packageVersion against CHANGELOG.md before concluding that a fixed defect recurred.

Publishing is automated through npm trusted publishing (OIDC, no stored npm token): every push to main runs the conformance gate and .github/workflows/publish.yml publishes the package only when package.json carries a version that npm does not have yet. Pre-release versions publish under the alpha dist tag, so npm install @galaxy-stack/ai-coder-core@latest never jumps to an unverified alpha.

Non-negotiable invariants

• One AI owns the run state. There is no hidden planner/reviewer agent.
• A model round may emit zero or more correlated tool calls. IDs must be non-empty and unique for the run; names may repeat with different arguments. The runtime preflights the complete batch, then executes it sequentially in emitted order.
• The model sees model-facing names; every result must match the host's model-name-to-canonical-ID mapping.
• Hosts provide structured prompt policy only. Runtime assembles and hashes the system prompt after capability and registry discovery, then formats the sole user task from AiCoderTaskContract. If command.run is active, the host must supply the exact concrete non-interactive interpreter contract; the runtime refuses missing/unknown shell metadata before a model request.
• Tool text is never parsed into trusted state. Only declared host effects can change inspection, write, validation, diff, plan, approval, or criterion evidence.
• Every host effect is checked against a per-canonical-tool capability policy. Built-in hosts derive that policy from the exported versioned core profile; divergent local copies are rejected at runtime startup.
• Every mutation uses a precondition and records distinct before/after state: create has a null beforeHash, delete has a null afterHash, and at least one hash is non-null. Later validation has explicit workspace/path scope.
• Validation and final diff evidence must match the final serialized workspace fingerprint before completion.
• A required acceptance criterion must be satisfied; waived does not close a required criterion.
• Checkpoints are cloned before validation, deeply frozen after validation, redacted, hashed with SHA-256, and resumed only from trusted host storage (or an explicit trusted_host provenance assertion).
• Cancellation makes an in-flight side-effect outcome unknown unless the host returns a structured result. Hosts must honor the supplied signal and absolute deadline.
• Identical retries, alternating successful tool cycles, varied failed mutations on one path/state, repeated validation failures on one fingerprint, and returning content hashes are bounded. Semantically identical validation, diff, and criterion evidence does not manufacture a new state transition; unresolved no-progress episodes pause with a checkpoint. Read-only observations follow the configured noProgressPolicy (advisory by default: escalating nudges at observationNudgeThresholds, blocked only after the final threshold; strict preserves the older first-incident accounting).
• Provider-reported context overflow checkpoints, compacts, and recounts before another model request. Mandatory state is never silently dropped to force a round through.
• Once a mutation has complete current validation and final-diff evidence, the next model turn is a bounded finalization turn with no tool definitions. Evidence-complete no-progress recovery uses the same boundary; ordinary inspect-then-edit or multi-step review work is not finalized early. A verified resume re-derives this boundary before its first model request.

Runtime flow

request
  -> capability + tool-policy snapshot
  -> core-owned prompt snapshot + canonical user-task contract
  -> bounded context assembly
  -> one streamed model round
  -> zero or more correlated tool calls
  -> atomic batch preflight (IDs, budget, visible registry, canonical JSON)
  -> sequential per-call schema/policy/approval/host adapter
  -> bounded untrusted observation + trusted declared effects
  -> repeat
  -> evidence-ready tool-free finalization turn
  -> final report candidate
  -> model-actionable evidence gate
  -> runtime-owned final-report persistence (when a store is configured)
  -> completion-gate trace + durable trace flush (when trace is configured)
  -> fresh workspace fingerprint
  -> deterministic completion gate
  -> completed

See ARCHITECTURE.md, PROMPT_CONTRACT.md, TOOL_EFFECT_PROFILE.md, and HOST_CONFORMANCE.md for integration contracts.

Source layout

src/
├── approval/   # fail-closed approval policy
├── context/    # context budget, token ledger, checkpoints, output bounds
├── ports/      # host capability interfaces and PortResult
├── prompt/     # versioned system prompt assembly
├── retrieval/  # bounded provider-neutral lexical evidence
├── runtime/    # run controller, state machine, completion gate, trace emitter
└── tools/      # schemas, descriptors, registry and provider protocol

Development

Requires Node.js 20 or newer.

npm install
npm run verify

Optional fast pre-push gate:

git config core.hooksPath .githooks

npm run verify runs strict TypeScript checks, all source tests, a clean build, and a public dist smoke test. npm pack --dry-run should also be checked before publishing or consuming the package from another repository.

npm test writes TEST_ERROR_LOG.md and per-run evidence under .galaxy/tests/: timestamped assertion results, failure stacks, test counts, commit and source fingerprint. The reporter is development-only and runs without a galaxy-code checkout. Raw tsx --test invocations bypass this reporter.

The deterministic end-to-end host gate lives in galaxy-code:

cd ../../galaxy-code
npm run check