HIP-0300 names llm among the optional tools and Python and Rust carry it,
but the TypeScript server had none, so an agent on @hanzo/mcp could ask
Kai a typed question and could not reach a model.
llm routes by action over api.hanzo.ai:
- query: POST /v1/chat/completions, model enso-auto unless named; "auto"
lets Enso pick. max_cost and max_latency_ms ride as X-Max-Cost and
X-Max-Latency-Ms. It returns the model that served (X-Routed-Model, else
the body's model) and the completion id feedback takes.
- models: GET /v1/models, each model's family, class and per-million
price as the catalog states it; family narrows to enso or kai.
- feedback: POST /v1/ai/feedback with request_id, signal and a 1-3
rating; an envelope that says error is an error.
Co-authored-by: Hanzo Dev <[email protected]>
exec gains run(): an argv with no shell, waited on up to a deadline, then
left running in exec's process table. npx and uvx use it with Python's argv
and a two-minute deadline; jq passes its filter as one argv word.
@hanzo/mcp 2.4.14
read returns numbered lines and the full sha256 hash, write only creates,
apply_patch takes old_text and new_text under base_hash, list walks with
depth, pattern and cursor, patch takes the Rust grammar, and search_text
takes a pattern and glob. rg now runs without a shell, so a pattern is never
a shell word.
@hanzo/mcp 2.4.13
src/zap.ts is a consumer seat on the unix socket of whichever process the
lock elected: zapd has no JS or wasm build, so this runtime joins as
mcp/hanzo-<pid> and never stands for router. browser and cdp carry Python's
action names, parameters and extension methods; headless Playwright covers
the core, navigation and tabs when no browser is registered. The test runs
PyPI zapd as the router in another process, with a fake extension.
@hanzo/mcp 2.4.12
describe was filtered out of the hanzo tool's resources, and the default
surface has no other tool that reaches it, so a model there could list a
resource's actions but not learn what one takes. It is a resource again:
hanzo(resource="describe", args={subsystem, op}), and a resource's action
list points at it.
Arguments ride in args, one object. A string was spread into
{"0": "{", ...}, and a key beside args, input among them, was merged in as an
argument; both reached the fleet as some other call. Both are now refused as
INVALID_ARGS before anything is sent, and the data alias is gone.
Co-authored-by: Hanzo Dev <[email protected]>
70a0a04 put tgrep first in the grep tool's description and left the test
holding the old words, so the suite failed on main.
Co-authored-by: Hanzo Dev <[email protected]>
The catalog is regenerated from cloud (plugin/gen-mcp-catalog): the graph tool
now carries all thirteen operations, answer, communities, diff, erase, extract,
ingest and path among them, and the Rust crate's copy is synced from it.
The hanzo tool sent {resource, action, ...} to a subsystem handler that reads
{op, input}, so every call from the default surface reached the fleet with no
op. It now sends {op: action, input: args}, the shape the Rust runtime sends,
lists a resource's actions when none is named, and offers only subsystems.
Co-authored-by: Hanzo Dev <[email protected]>
Every suite had stopped executing. ts-jest peers on `typescript >=4.3 <7`
and this repo builds against 7, so all twenty files died inside ConfigSet
with "Cannot read properties of undefined (reading 'fileExists')" — twenty
failures, zero tests, and nothing to read them by because the push gate
deliberately runs typecheck and build rather than jest.
swc transforms instead: it strips types rather than asking the compiler
to, so it has no TypeScript version to disagree with, and `tsc --noEmit`
already answers the question ts-jest was answering twice.
Running as real ESM then exposed what the CommonJS fallback had hidden.
jest.mock does not hoist there, so a static import binds the real module
and the suite fails on `mockReturnValue is not a function` — an absent
mock reported as a broken one. The search, autogui and ui suites now
register through unstable_mockModule and import after it. One of them had
never mocked fs at all: it cast fs.promises to a mocked type and called
mockImplementation on the real module.
384 tests, twenty suites, all passing.
The seven resources this offered had drifted from the fleet it names: paas is
platform, storage is s3, auth folded into iam, and iam alone carries 97
operations against the handful the hand-written tool reached. It also dialled
four hosts for one API.
The names come from cloud's typed operations now, so this client cannot come to
disagree with the API about what exists. The withholding rule is asked of cloud
rather than restated here — a client deriving its set from the raw catalog offers
what the fleet refuses.
The default surface is unchanged at 22 tools; the fleet sits behind hanzo, whose
resource enum is derived rather than listed.
`fetch:search` scraped html.duckduckgo.com and pulled results out of a regex
over `class="result__title"`. Measured 2026-08-20: that page answers HTTP 202 —
DuckDuckGo's anti-bot challenge — and the markup carries no `result__title` at
all. So the regex matched nothing and the tool returned `{results: [], count: 0}`
for EVERY query: the identical answer it gives when the web genuinely has
nothing. Blind rendered as empty, with no way for a caller to tell them apart,
which is exactly why nobody noticed.
It now asks POST /v1/websearch — the meta-search we ship — reading the base URL
and credential from the same env the tracker tool reads, so the MCP has one way
to reach cloud rather than a second one here.
The failure shape is the point:
no credential -> NO_CREDENTIAL, never an empty result list
cloud refuses -> its own words verbatim ("sign in to search the web"),
because a 401 and a 500 are different problems and
flattening both into "search failed" makes an outage
look like a bad query
results -> carries WHICH ENGINES answered, so a zero-result search
with engines listed is a real empty and one with none is
a search that did not happen
HONEST GAP: the committed test cannot run. The repo declares typescript ^7.0.2
against ts-jest ^29.4.6, which does not support TS7, so `npx jest` dies in
_resolveTsConfig on "Cannot read properties of undefined (reading 'fileExists')"
— for the pre-existing suites too (edit.test.ts: 0 tests). `tsc --noEmit` is
clean repo-wide; only the transform is dead. The eight assertions were run
against the esbuild-bundled tool instead and all pass; they execute under jest
the moment the toolchain is fixed.
Co-authored-by: Hanzo Dev <[email protected]>
An agent could already keep a todo list (`tasks`), but only on its own disk.
Nothing here reached the board a human looks at, so "what is this agent doing"
had no answer outside the agent. These four tools are the cloud /v1/tracker
surface — the ONE work-item primitive — as MCP tools.
They are deliberately NOT called tasks_*. Three planes are easy to braid and
cloud apps/tracker/contract.go is law about it: a tracker Issue is a work item,
hanzoai/tasks is durable async execution, and the local `tasks` tool is a
private file at ~/.hanzo/todos.json. Naming these tasks_* would have collided
with that third one and pointed callers at the plane nobody can see.
Linking a run needed no new field. An agent's run is a SESSION — "mission" is
not modeled anywhere in the fleet — and the tracker contract already defines
extRef as "a link INTO another plane", so `session` writes the anchor
`session:<id>` and hanzo.app renders that session's live status on the row.
tracker_create defaults source to agent, because the board's ?source=agent
filter is only true if agents say so.
Cloud's own refusal reaches the caller verbatim — "unknown status filter" is
worth more to an agent than a generic failure — and the org is never sent: it
is minted server-side from the bearer, and a tool that sends one is a tool
asking to be trusted about tenancy.
NOTE: the jest suite cannot RUN on main right now — TypeScript 7.0.2 is
installed and ts-jest 29.4.6 cannot read its compiler API, so all 18 suites
fail to load. That break predates this commit and is orthogonal to it (verified
on a clean origin/main checkout). These tools were verified twice: 20 jest tests
green under the TS 5 toolchain, and 11 runtime checks through the shipped
esbuild bundle under main's current dependency state.
Co-authored-by: Hanzo Dev <[email protected]>
Add code_search / code_context / code_ask / code_index — one MCP tool per
api.hanzo.ai/v1/code endpoint — so @hanzo/dev and any MCP agent gain per-org
code search, budget-packed context, and cited RAG answers.
Auth mirrors hanzo-cloud.ts exactly: the caller's Hanzo bearer from
HANZO_API_KEY (or API_KEY/API_TOKEN/HANZO_TOKEN). The org is minted
server-side from that identity (principal gate) — a client never passes an
org. Output is requested as markdown (?format=md) so the LLM reads a
token-thrifty table; a non-2xx surfaces as a clear isError string. The tools
join the canonical HIP-0300 surface (allUnifiedTools), so tools/list exposes
all four over stdio.
test: hermetic local-server suite (10 tests) asserts method/path/format=md/
Bearer, no-org-leak, and arg + auth failures. Update the two tool-list
registry tests for gimp + the four code tools, and fix a pre-existing
ts-jest rootDir error that blocked every suite importing test/setup.ts.
Co-authored-by: Hanzo Dev <[email protected]>
* feat(fetch): x402 Payment Required handling + first unified-tool tests
Adds HTTP 402 (x402) parsing to the unified fetch tool so AI agents can
surface payment quotes from x402-gated endpoints and replay with X-PAYMENT.
- request / fetch / head detect status === 402 and return a structured
payment_required envelope (parsed accepts[], x402-version, www-authenticate)
- new optional 'payment' input: pre-encoded base64 string sent verbatim, or
a JSON object that is base64-encoded into X-PAYMENT before retry
- adds the first Jest test file for the HIP-0300 unified surface
(test/tools/unified/fetch.test.ts) covering 200, 402, payment object, and
payment string paths against an in-process http.createServer fixture
Also fixes test/setup.ts so the existing test suite actually runs:
- imports 'jest' from @jest/globals (jest is not a global under ESM)
- ESM-safe __dirname via fileURLToPath(import.meta.url)
Net effect: 169 previously-unrunnable tests can now start; 7/7 new fetch
tests pass; remaining failures are pre-existing test bugs unrelated to this
PR (CommonJS require() in ESM mode, missing mocks, etc.).
No new dependencies, no breaking changes to fetch's existing semantics.
* test: anchor setup.ts on process.cwd() to fix Node 18/20 ESM CI
`test/setup.ts` used `fileURLToPath(import.meta.url)` to derive its own
directory, but `ts-jest`'s handling of `import.meta` inside
`setupFilesAfterEnv` is fragile across Node versions — every test suite
failed on Node 18.x and 20.x with TS1343 ("\'import.meta\' meta-property
is only allowed when \'--module\' is es2020/...\"), even though the
root tsconfig and ts-jest's transform tsconfig both set
`module: ESNext`.
Tests always run from the project root, so `path.join(process.cwd(),
'test', ...)` is a stable anchor that doesn't depend on how the setup
file is loaded.
Local: 15/16 suites pass after the fix (2 unrelated shell.test.ts timing
flakes remain).
* fix(ci): suppress TS2307 on optional jsautogui dynamic import
The Node 20 CI job was failing two test suites — test/config/
configuration.test.ts and test/integration/mcp-server.test.ts — with:
src/autogui/adapters/jsautogui.ts:37:37 - error TS2307: Cannot find
module 'jsautogui' or its corresponding type declarations.
while the actual jest run itself reported 326/326 tests passing in the
suites it could load. Root cause: jsautogui is in optionalDependencies
and ships native bindings that npm may skip on some platforms. When
the package (and its bundled .d.ts) isn't present, ts-jest's transform
pass fails the whole suite at type-check time even though the runtime
code path is already guarded by try/catch + AutoGUINotAvailableError.
Adds a localised `// @ts-ignore` on the single dynamic-import line,
with a comment explaining why. The runtime behaviour is unchanged —
if jsautogui isn't installed, the catch arm still throws
AutoGUINotAvailableError as before. Confirmed locally that the
previously-failing test/config/configuration.test.ts now passes both
with jsautogui present and with node_modules/jsautogui removed
(simulating the Ubuntu CI install).
No code logic changed; package.json and package-lock.json untouched.
---------
Co-authored-by: Abhishek Krishna <[email protected]>
Source fixes:
- Fix MCP SDK v1.18.0 callback signatures (extra param)
- Fix searchTool default type to 'all' when unspecified
- Fix file-ops maxDepth boundary check (> to >=)
- Fix type annotations in multi-framework-tools, agent-tools
- Fix secure-tunnel config property types
- Add resetUrlHelper export for test isolation
Test fixes:
- Fix url-helper tests for actual path resolution behavior
- Fix configuration/mcp-server tests for actual tool counts
- Fix search-engine test for actual ENOENT error messages
- Fix autogui tests for actual schema (required: [])
- Fix shell tests to use script files instead of inline bash
- Fix unified-ui-tool alias test expectations
- Fix test setup: per-suite unique temp dirs prevent parallel interference
- Fix CLI to properly handle --version flag and serve command
- Made serve command the default command
- Added server.js as entry point wrapper
- Version bumped to 2.0.1 for npm release
- Organized test files into test/ directory
## Core Implementation
- Unified search engine with strategy pattern for extensible search types
- Full OpenAI MCP specification compliance for search and fetch tools
- Multi-modal search strategies: Symbol, AST, Vector, Text, and File search
- Automatic strategy selection based on query characteristics
## Security & Remote Access
- Secure ngrok tunnel integration with automatic detection
- Multi-method authentication (Bearer token, API keys, JWT)
- Post-quantum TLS configuration support
- Rate limiting and CORS protection
- Access logging and monitoring
- Only exposes files when ngrok credentials are present
## Testing & CI
- 102 tests with 85% coverage on critical paths
- GitHub Actions CI workflow for automated testing
- Node.js 18.x and 20.x compatibility testing
- Coverage reporting to Codecov
- Security audit checks
## Documentation
- Comprehensive documentation in LLM.md
- Security guide in docs/SECURITY.md
- .npmrc excluded from repository for security
This implementation provides a production-ready search system for AI tools like ChatGPT and Claude Desktop.
zeekay
