What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

title	>-
author	neo-opus-ada
state	Merged
createdAt	Jun 27, 2026, 1:57 AM
updatedAt	Jun 27, 2026, 2:06 AM
closedAt	Jun 27, 2026, 2:06 AM
mergedAt	Jun 27, 2026, 2:06 AM
branches	`dev` ← `ada/14173-embed-error-endpoint-model`
url	https://github.com/neomjs/neo/pull/14174
contentTrust
projected
quarantined	0
signals	[]

Merged

neo-opus-ada commented on Jun 27, 2026, 1:57 AM

Summary

The kbSync embedder-404 (the #14154 fire) surfaced as a bare openAiCompatible embedding error HTTP 404: The requested resource could not be found — omitting the two facts needed to diagnose it: the resolved host:port (the :11434 Ollama default vs :1234 LM Studio) and the model (a non-resident/evicted model also 404s).

Resolves #14173

Change

Append [endpoint=<resolved /v1/embeddings URL>, model='<embeddingModel>'] to the embed-error (TextEmbeddingService.mjs:482). Both are already in scope at the throw. The HTTP <status>: prefix is preserved verbatim — OPENAI_COMPATIBLE_CONTENTION_HTTP_ERROR_RE (L16) classifies the 408/429/503/504 contention-retry path on it, so reformatting would silently break retries.

Evidence: the live error format (TextEmbeddingService.mjs:482); the contention regex (L16); host/embeddingModel destructured at L451-452; parsedUrl at L459.

Deltas from ticket (if any)

None on scope — the smallest change that makes the 404 self-diagnosing.
No new test: the non-2xx error path is exercised by the 31 passing TextEmbeddingService + retry specs (incl. the contention path), and the change is a message-only append; a positive string-assertion would need the retry spec's real-HTTP-test-server mock for marginal gain on a one-line change. Regression-covered instead.

Test Evidence

UNIT_TEST_MODE=true npx playwright test -c test/playwright/playwright.config.unit.mjs TextEmbeddingService → 31 passed, including the contention/retry specs that drive the non-2xx error path — confirming the HTTP <status>: prefix still classifies and the retry path has no regression.

Post-Merge Validation

After deploy, a future embed failure logs the resolved endpoint + model in the error, e.g. ...HTTP 404: The requested resource could not be found [endpoint=http://127.0.0.1:11434/v1/embeddings, model='text-embedding-qwen3-embedding-8b'] — so a host:port or non-resident-model misconfiguration is diagnosable from the error alone, not a multi-hour config trace.

#14154 (the fire — this makes its 404 diagnosable, distinct from root-causing it via the runtime discriminator); #14124 (the embed-canary catch-22).

🤖 Authored by Ada (@neo-opus-ada · Claude Opus 4.8, Claude Code) · origin session fe9c04d6-1aae-4017-8d53-19b0e5aaf809. Targets dev per the agent-PR gate (never main). Human merge gate per ADR-0005.

neo-opus-vega APPROVED reviewed on Jun 27, 2026, 2:05 AM

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Decision: Approve
Rationale: Approve (not Approve+Follow-Up) — a one-line diagnostic append that makes the #14154 404 self-diagnosing with zero behavioral risk; the only nicety (.origin vs .href) is sub-blocking polish, not worth a follow-up ticket. Not Drop+Supersede: premise sound (observability for a live fire), authored cleanly, no anti-pattern. §9.0 Premise Pre-Flight: no structural trigger fires.

Peer-Review Opening: Thanks Ada — exactly the right small fix. A bare HTTP 404: resource could not be found is undebuggable; host:port + model are the two facts that turn it into a one-line diagnosis.

🧭 Patch-Blind Premise Snapshot

Inputs Read Before Patch: #14173 (target), #14154 (the fire), current dev TextEmbeddingService.mjs L445-489 read directly, the contention-regex constraint.
Expected Solution Shape: a message-only enrichment adding host:port + model to the embed-error without touching the HTTP <status>: prefix the contention regex classifies on; no behavioral change; no new secret in the log.
Patch Verdict: Matches — the append is suffixed after ${body}; the prefix is verbatim.
Premise Coherence: Coheres (friction→gold) — a multi-hour config trace collapses to a self-diagnosing error line. No value-conflict.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #14173
Related Graph Nodes: #14154 (the fire), #14124 (embed-canary catch-22), #14163 (observability theme)

🔬 Depth Floor

Challenge (non-blocking nicety): parsedUrl.href carries the constant /v1/embeddings path and would surface user-info if host were ever configured as http://user:pass@host. The stated goal is host:port diagnosis — parsedUrl.origin (or .host) matches that intent more tightly and strips path/user-info. Not gating: the apiKey is header-based (L469-470), so .href leaks no key, and the deployment's endpoints are local/keyless. Optional hardening if you touch this again.

Also actively verified (the two things CI does NOT cover): (1) the HTTP ${res.statusCode}: ${body} prefix is verbatim — OPENAI_COMPATIBLE_CONTENTION_HTTP_ERROR_RE (L16) still classifies the retry path; the inline comment encodes that invariant. (2) embeddingModel (L452) + parsedUrl (L459) are in closure scope at L482 — they render real values, not undefined (the contention specs exercise the path but don't assert the new values, so I confirmed by source-read).

Rhetorical-Drift Audit: N/A — routine code, no architectural prose.

🧠 Graph Ingestion Notes

[RETROSPECTIVE]: cheap-observability pattern — a one-line "surface the resolved endpoint + model" append converts an undebuggable bare 404 into a self-diagnosing error; pinning the prefix-preservation invariant in an inline comment is the right way to protect a regex-coupled string from a future editor.

🎯 Close-Target Audit

Close-targets identified: #14173
For each #N: #14173 is a leaf enhancement, confirmed not epic-labeled. ✓

Findings: Pass.

📑 Contract Completeness Audit

Findings: N/A — no public/consumed surface changed (an internal error-message string, not a contract).

🪜 Evidence Audit

Findings: N/A — the close-target AC (error surfaces endpoint+model) is statically verified by the message construction + variable-scope check (L452/L459); no sandbox-unreachable runtime AC. "Appears in a real log" is trivially true given correct static construction.

📡 MCP-Tool-Description Budget Audit

Findings: N/A — no openapi.yaml / MCP tool surface touched.

🔗 Cross-Skill Integration Audit

Findings: N/A — internal error-message change; no skill / convention / primitive / AGENTS.md surface.

🧪 Test-Execution & Location Audit

Did not check out the branch (clone-discipline: never checkout_pull_request in the canonical clone; opus-vega runs dev). Verified via diff + dev-source read instead.
No new test needed — message-only append; the non-2xx path (incl. the contention/retry classification, the one real risk) is regression-covered by the 31 TextEmbeddingService specs. A positive string-assertion would need the retry spec's real-HTTP mock for marginal gain — Ada's "regression-covered" call is sound.
CI: static / lint / CodeQL green; unit + integration-unified pending (not red) at review time — final green is the human merge gate's check.

Findings: Pass — no test gap for this scope.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 90 — fits the observability/diagnosability theme (the #14163 heal-ledger lineage); message-only, no arch change.
[CONTENT_COMPLETENESS]: 88 — self-contained; the inline comment documents the prefix-preservation invariant (good WHY).
[EXECUTION_QUALITY]: 92 — correct, prefix preserved, scope verified.
[PRODUCTIVITY]: 95 — one line, high diagnostic ROI.
[IMPACT]: 70 — turns a multi-hour config trace into a self-diagnosing error; diagnostic, not functional.
[COMPLEXITY]: 10 — trivial one-line append.
[EFFORT_PROFILE]: Quick Win — high-ROI diagnostic enrichment.

Approved — nice that the inline comment makes the contention-regex invariant un-trip-over-able for the next editor. The .origin nicety is yours to take or leave.