gille-inference clients

This package contains two deliberately separate zero-dependency clients:

• hs is the friend-facing invite, streaming chat, and usage client described below.
• m5 is the profile-based, Keychain-backed owner-agent client and stdio MCP bridge.

The box-local operator CLI remains src/homeserver/cli.ts; neither packaged client replaces it. All example.com URLs below are reserved documentation examples; replace them with your deployment URL.

Requires Node 18+ (uses built-in fetch). No external dependencies.

Owner-client 1.4.1 compatibility

The 1.4.1 m5 client requires the gateway's v9 schema-grounding contract for code_loop. Its doctor reports MCP catalogue reachability without calling metered inference; bridge errors also repeat safe diagnostic codes in the visible message for MCP hosts that hide error data. Coordinate the client and gateway upgrade: v8/v9 terminal results are deliberately not interchangeable. Restart/reconnect long-lived MCP bridge processes after installing the accepted package. The hs friend-facing API is unchanged. Publication, installation, and gateway deployment are separate operations; source documentation does not prove any occurred.

Install

npm install -g gille-inference

Or zero-install with npx:

npx --package gille-inference hs ask "What is the capital of France?"

Alternatively, download directly from the gateway:

curl -fsSL https://inference.example.com/hs -o ~/bin/hs && chmod +x ~/bin/hs

Quickstart

# 1. Redeem your invite code — saves credentials to ~/.config/hs/config.json
hs redeem inv_xxxxxxxxxxxxxxxx

# 2. List the models your key may use
hs models

# 3. Ask a question (streams tokens as they arrive)
hs ask "What is the capital of France?"
hs ask -m qwen3.5-35b-a3b --system "You are a code reviewer." "Review this: ..."

# 4. Check your tier, allowed models, and credit usage
hs usage

# 5. Show stored credentials
hs whoami

How it works

hs ask calls POST /v1/chat/completions with stream: true. hs models calls GET /v1/models. hs usage calls GET /portal/me. The gateway is plain OpenAI-compatible — you can swap hs for any OpenAI SDK at any time by pointing it at https://inference.example.com/v1.

More

Your deployment's root URL serves the portal, invite flow, and client documentation.

Owner-agent m5 client

m5 requires a named profile and resolves its credential internally from macOS Keychain. It has no bearer-token environment variable, config field, or argv flag. Public profiles require HTTPS; HTTP is accepted only for an explicitly selected private endpoint, and redirects fail closed.

m5 --profile codex doctor
m5 --profile codex models
printf '%s' '{"model":"mellum","prompt":"Summarize this."}' | m5 --profile codex ask
m5 --profile codex mcp

m5 ask prints structured JSON including finish_reason, explicit truncated, and content-blind usage. A token-limit finish returns truncated:true so scripts can retry with a higher max_tokens instead of mistaking an empty or partial answer for a clean completion. A direct ask applies a 30,000 ms single-request timeout by default; --timeout-ms <integer> selects a bounded 1,000–600,000 ms alternative for that call only:

printf '%s' '{"model":"mellum","prompt":"Summarize this."}' \
  | m5 --profile codex --timeout-ms 90000 ask

A longer client bound does not raise server caps or guarantee completion.

For a real owner execution, set traffic_purpose to organic in the ask or code request. The structured ask or code_loop_result output may then include a feedback_handle. After reviewing the real result, submit one exact usefulness judgment with the same profile that ran it:

printf '%s' '{"feedback_handle":"01234567-89ab-cdef-0123-456789abcdef","usefulness":"pass"}' \
  | m5 --profile codex feedback submit

The command sends only the selected usefulness value and returns recorded or unchanged. Usefulness is supplied by the reviewer after execution; the client never infers it from structural verification or other automatic signals.

The MCP bridge returns stable, redacted transport diagnostics (failure_layer, diagnostic_code, retryable, and fixed remediation) for DNS, routing, connection, TLS, timeout, gateway-health, and authentication failures. Three local layers name failures before any network access: public_route_unconfigured / private_route_unconfigured (the profile has no route — configure it, never substitute loopback), local_tailnet_unavailable (private path with the tailnet down — start Tailscale, then rerun doctor), and the already-emitted connector_transport. A missing profile routes to the secret-safe provision flow. Adoption reports return a scoped acknowledgement: retention: "retained" means the row was stored, retention: "aggregated" means the bounded telemetry cap was reached but the observation was folded into a safe aggregate, and retention: "dropped" identifies a telemetry-only refusal. A telemetry cap is never an M5 inference limit: inference_availability: "unaffected", and only the report should wait until the next UTC day. A connector/transport failure spools the content-free report locally under ~/.config/m5/adoption-spool/ (redacted, 0600, newest 100 retained) and reports evidence_recovery: {"status":"spooled","spool_id":…,"action":"retry_same_tool_call"}; if the spool write itself fails the status is spool_failed with the same retry action, and with no spool configured the legacy not_recorded shape is kept. Recovery is deterministic: retry the same report tool call after the gateway recovers — the spool file is the backstop, not a queue.

On the public path, a Cloudflare HTTP 530 page containing 1033 reports cloudflare_tunnel_unavailable and directs the operator to cloudflared and tunnel connections. Another Cloudflare 530 reports cloudflare_origin_unresolved; inspect its 1xxx code before attributing a more precise cause. HTTP 502 reports the upstream route failure while explicitly leaving its specific cause unknown. The client never copies an error-page body into its output. No report payload is echoed, and no locator or credential ever enters diagnostics.

code_loop_result is safe to repeat for the same durable work id. The bridge automatically retries that one read-only tool call once after a retryable transport or gateway-health failure, using the same JSON-RPC request and work id. If both attempts fail, result_recovery reports retry_exhausted; it tells the caller to retry the same work id only when the final error remains retryable, otherwise to follow that error's remediation. Structured unknown work_id and terminal result unavailable after restart responses are returned unchanged and are never treated as transport failures.

Provisioning a new owner-agent profile

m5 provision is an owner-attended macOS operator ceremony. It creates the non-secret profile, invokes the fixed live-gateway mint path over SSH, stores the one-time bearer through the macOS Keychain prompt path, and finishes with a redacted doctor result:

m5 --profile pi \
  --public-gateway-url https://inference.example.com \
  --m5-host magnus@m5 \
  provision

The command requires a non-interactive, owner-authorized SSH path to the M5 host. It rejects an existing profile URL mismatch or Keychain item rather than silently replacing either; reconcile an existing credential through the normal rotation procedure first. It never accepts or prints bearer data.

See the m5 agent client guide for the profile schema, Keychain account mapping, structured code commands, claude-config installation/versioning contract, and security boundary. The server-side cage and diff-only result are authoritative; the client never applies a returned diff.