@intent-systems/nexus 2026.1.5-3

package/skills/local-places/src/local_places/google_places.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import httpx
+from fastapi import HTTPException
+
+from local_places.schemas import (
+    LatLng,
+    LocationResolveRequest,
+    LocationResolveResponse,
+    PlaceDetails,
+    PlaceSummary,
+    ResolvedLocation,
+    SearchRequest,
+    SearchResponse,
+)
+
+GOOGLE_PLACES_BASE_URL = os.getenv(
+    "GOOGLE_PLACES_BASE_URL", "https://places.googleapis.com/v1"
+)
+logger = logging.getLogger("local_places.google_places")
+
+_PRICE_LEVEL_TO_ENUM = {
+    0: "PRICE_LEVEL_FREE",
+    1: "PRICE_LEVEL_INEXPENSIVE",
+    2: "PRICE_LEVEL_MODERATE",
+    3: "PRICE_LEVEL_EXPENSIVE",
+    4: "PRICE_LEVEL_VERY_EXPENSIVE",
+}
+_ENUM_TO_PRICE_LEVEL = {value: key for key, value in _PRICE_LEVEL_TO_ENUM.items()}
+
+_SEARCH_FIELD_MASK = (
+    "places.id,"
+    "places.displayName,"
+    "places.formattedAddress,"
+    "places.location,"
+    "places.rating,"
+    "places.priceLevel,"
+    "places.types,"
+    "places.currentOpeningHours,"
+    "nextPageToken"
+)
+
+_DETAILS_FIELD_MASK = (
+    "id,"
+    "displayName,"
+    "formattedAddress,"
+    "location,"
+    "rating,"
+    "priceLevel,"
+    "types,"
+    "regularOpeningHours,"
+    "currentOpeningHours,"
+    "nationalPhoneNumber,"
+    "websiteUri"
+)
+
+_RESOLVE_FIELD_MASK = (
+    "places.id,"
+    "places.displayName,"
+    "places.formattedAddress,"
+    "places.location,"
+    "places.types"
+)
+
+
+class _GoogleResponse:
+    def __init__(self, response: httpx.Response):
+        self.status_code = response.status_code
+        self._response = response
+
+    def json(self) -> dict[str, Any]:
+        return self._response.json()
+
+    @property
+    def text(self) -> str:
+        return self._response.text
+
+
+def _api_headers(field_mask: str) -> dict[str, str]:
+    api_key = os.getenv("GOOGLE_PLACES_API_KEY")
+    if not api_key:
+        raise HTTPException(
+            status_code=500,
+            detail="GOOGLE_PLACES_API_KEY is not set.",
+        )
+    return {
+        "Content-Type": "application/json",
+        "X-Goog-Api-Key": api_key,
+        "X-Goog-FieldMask": field_mask,
+    }
+
+
+def _request(
+    method: str, url: str, payload: dict[str, Any] | None, field_mask: str
+) -> _GoogleResponse:
+    try:
+        with httpx.Client(timeout=10.0) as client:
+            response = client.request(
+                method=method,
+                url=url,
+                headers=_api_headers(field_mask),
+                json=payload,
+            )
+    except httpx.HTTPError as exc:
+        raise HTTPException(status_code=502, detail="Google Places API unavailable.") from exc
+
+    return _GoogleResponse(response)
+
+
+def _build_text_query(request: SearchRequest) -> str:
+    keyword = request.filters.keyword if request.filters else None
+    if keyword:
+        return f"{request.query} {keyword}".strip()
+    return request.query
+
+
+def _build_search_body(request: SearchRequest) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "textQuery": _build_text_query(request),
+        "pageSize": request.limit,
+    }
+
+    if request.page_token:
+        body["pageToken"] = request.page_token
+
+    if request.location_bias:
+        body["locationBias"] = {
+            "circle": {
+                "center": {
+                    "latitude": request.location_bias.lat,
+                    "longitude": request.location_bias.lng,
+                },
+                "radius": request.location_bias.radius_m,
+            }
+        }
+
+    if request.filters:
+        filters = request.filters
+        if filters.types:
+            body["includedType"] = filters.types[0]
+        if filters.open_now is not None:
+            body["openNow"] = filters.open_now
+        if filters.min_rating is not None:
+            body["minRating"] = filters.min_rating
+        if filters.price_levels:
+            body["priceLevels"] = [
+                _PRICE_LEVEL_TO_ENUM[level] for level in filters.price_levels
+            ]
+
+    return body
+
+
+def _parse_lat_lng(raw: dict[str, Any] | None) -> LatLng | None:
+    if not raw:
+        return None
+    latitude = raw.get("latitude")
+    longitude = raw.get("longitude")
+    if latitude is None or longitude is None:
+        return None
+    return LatLng(lat=latitude, lng=longitude)
+
+
+def _parse_display_name(raw: dict[str, Any] | None) -> str | None:
+    if not raw:
+        return None
+    return raw.get("text")
+
+
+def _parse_open_now(raw: dict[str, Any] | None) -> bool | None:
+    if not raw:
+        return None
+    return raw.get("openNow")
+
+
+def _parse_hours(raw: dict[str, Any] | None) -> list[str] | None:
+    if not raw:
+        return None
+    return raw.get("weekdayDescriptions")
+
+
+def _parse_price_level(raw: str | None) -> int | None:
+    if not raw:
+        return None
+    return _ENUM_TO_PRICE_LEVEL.get(raw)
+
+
+def search_places(request: SearchRequest) -> SearchResponse:
+    url = f"{GOOGLE_PLACES_BASE_URL}/places:searchText"
+    response = _request("POST", url, _build_search_body(request), _SEARCH_FIELD_MASK)
+
+    if response.status_code >= 400:
+        logger.error(
+            "Google Places API error %s. response=%s",
+            response.status_code,
+            response.text,
+        )
+        raise HTTPException(
+            status_code=502,
+            detail=f"Google Places API error ({response.status_code}).",
+        )
+
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        logger.error(
+            "Google Places API returned invalid JSON. response=%s",
+            response.text,
+        )
+        raise HTTPException(status_code=502, detail="Invalid Google response.") from exc
+
+    places = payload.get("places", [])
+    results = []
+    for place in places:
+        results.append(
+            PlaceSummary(
+                place_id=place.get("id", ""),
+                name=_parse_display_name(place.get("displayName")),
+                address=place.get("formattedAddress"),
+                location=_parse_lat_lng(place.get("location")),
+                rating=place.get("rating"),
+                price_level=_parse_price_level(place.get("priceLevel")),
+                types=place.get("types"),
+                open_now=_parse_open_now(place.get("currentOpeningHours")),
+            )
+        )
+
+    return SearchResponse(
+        results=results,
+        next_page_token=payload.get("nextPageToken"),
+    )
+
+
+def get_place_details(place_id: str) -> PlaceDetails:
+    url = f"{GOOGLE_PLACES_BASE_URL}/places/{place_id}"
+    response = _request("GET", url, None, _DETAILS_FIELD_MASK)
+
+    if response.status_code >= 400:
+        logger.error(
+            "Google Places API error %s. response=%s",
+            response.status_code,
+            response.text,
+        )
+        raise HTTPException(
+            status_code=502,
+            detail=f"Google Places API error ({response.status_code}).",
+        )
+
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        logger.error(
+            "Google Places API returned invalid JSON. response=%s",
+            response.text,
+        )
+        raise HTTPException(status_code=502, detail="Invalid Google response.") from exc
+
+    return PlaceDetails(
+        place_id=payload.get("id", place_id),
+        name=_parse_display_name(payload.get("displayName")),
+        address=payload.get("formattedAddress"),
+        location=_parse_lat_lng(payload.get("location")),
+        rating=payload.get("rating"),
+        price_level=_parse_price_level(payload.get("priceLevel")),
+        types=payload.get("types"),
+        phone=payload.get("nationalPhoneNumber"),
+        website=payload.get("websiteUri"),
+        hours=_parse_hours(payload.get("regularOpeningHours")),
+        open_now=_parse_open_now(payload.get("currentOpeningHours")),
+    )
+
+
+def resolve_locations(request: LocationResolveRequest) -> LocationResolveResponse:
+    url = f"{GOOGLE_PLACES_BASE_URL}/places:searchText"
+    body = {"textQuery": request.location_text, "pageSize": request.limit}
+    response = _request("POST", url, body, _RESOLVE_FIELD_MASK)
+
+    if response.status_code >= 400:
+        logger.error(
+            "Google Places API error %s. response=%s",
+            response.status_code,
+            response.text,
+        )
+        raise HTTPException(
+            status_code=502,
+            detail=f"Google Places API error ({response.status_code}).",
+        )
+
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        logger.error(
+            "Google Places API returned invalid JSON. response=%s",
+            response.text,
+        )
+        raise HTTPException(status_code=502, detail="Invalid Google response.") from exc
+
+    places = payload.get("places", [])
+    results = []
+    for place in places:
+        results.append(
+            ResolvedLocation(
+                place_id=place.get("id", ""),
+                name=_parse_display_name(place.get("displayName")),
+                address=place.get("formattedAddress"),
+                location=_parse_lat_lng(place.get("location")),
+                types=place.get("types"),
+            )
+        )
+
+    return LocationResolveResponse(results=results)

package/skills/local-places/src/local_places/main.py

@@ -0,0 +1,65 @@
+import logging
+import os
+
+from fastapi import FastAPI, Request
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from local_places.google_places import get_place_details, resolve_locations, search_places
+from local_places.schemas import (
+    LocationResolveRequest,
+    LocationResolveResponse,
+    PlaceDetails,
+    SearchRequest,
+    SearchResponse,
+)
+
+app = FastAPI(
+    title="My API",
+    servers=[{"url": os.getenv("OPENAPI_SERVER_URL", "http://maxims-macbook-air:8000")}],
+)
+logger = logging.getLogger("local_places.validation")
+
+
+@app.get("/ping")
+def ping() -> dict[str, str]:
+    return {"message": "pong"}
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    logger.error(
+        "Validation error on %s %s. body=%s errors=%s",
+        request.method,
+        request.url.path,
+        exc.body,
+        exc.errors(),
+    )
+    return JSONResponse(
+        status_code=422,
+        content=jsonable_encoder({"detail": exc.errors()}),
+    )
+
+
+@app.post("/places/search", response_model=SearchResponse)
+def places_search(request: SearchRequest) -> SearchResponse:
+    return search_places(request)
+
+
+@app.get("/places/{place_id}", response_model=PlaceDetails)
+def places_details(place_id: str) -> PlaceDetails:
+    return get_place_details(place_id)
+
+
+@app.post("/locations/resolve", response_model=LocationResolveResponse)
+def locations_resolve(request: LocationResolveRequest) -> LocationResolveResponse:
+    return resolve_locations(request)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run("local_places.main:app", host="0.0.0.0", port=8000)

package/skills/local-places/src/local_places/schemas.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class LatLng(BaseModel):
+    lat: float = Field(ge=-90, le=90)
+    lng: float = Field(ge=-180, le=180)
+
+
+class LocationBias(BaseModel):
+    lat: float = Field(ge=-90, le=90)
+    lng: float = Field(ge=-180, le=180)
+    radius_m: float = Field(gt=0)
+
+
+class Filters(BaseModel):
+    types: list[str] | None = None
+    open_now: bool | None = None
+    min_rating: float | None = Field(default=None, ge=0, le=5)
+    price_levels: list[int] | None = None
+    keyword: str | None = Field(default=None, min_length=1)
+
+    @field_validator("types")
+    @classmethod
+    def validate_types(cls, value: list[str] | None) -> list[str] | None:
+        if value is None:
+            return value
+        if len(value) > 1:
+            raise ValueError(
+                "Only one type is supported. Use query/keyword for additional filtering."
+            )
+        return value
+
+    @field_validator("price_levels")
+    @classmethod
+    def validate_price_levels(cls, value: list[int] | None) -> list[int] | None:
+        if value is None:
+            return value
+        invalid = [level for level in value if level not in range(0, 5)]
+        if invalid:
+            raise ValueError("price_levels must be integers between 0 and 4.")
+        return value
+
+    @field_validator("min_rating")
+    @classmethod
+    def validate_min_rating(cls, value: float | None) -> float | None:
+        if value is None:
+            return value
+        if (value * 2) % 1 != 0:
+            raise ValueError("min_rating must be in 0.5 increments.")
+        return value
+
+
+class SearchRequest(BaseModel):
+    query: str = Field(min_length=1)
+    location_bias: LocationBias | None = None
+    filters: Filters | None = None
+    limit: int = Field(default=10, ge=1, le=20)
+    page_token: str | None = None
+
+
+class PlaceSummary(BaseModel):
+    place_id: str
+    name: str | None = None
+    address: str | None = None
+    location: LatLng | None = None
+    rating: float | None = None
+    price_level: int | None = None
+    types: list[str] | None = None
+    open_now: bool | None = None
+
+
+class SearchResponse(BaseModel):
+    results: list[PlaceSummary]
+    next_page_token: str | None = None
+
+
+class LocationResolveRequest(BaseModel):
+    location_text: str = Field(min_length=1)
+    limit: int = Field(default=5, ge=1, le=10)
+
+
+class ResolvedLocation(BaseModel):
+    place_id: str
+    name: str | None = None
+    address: str | None = None
+    location: LatLng | None = None
+    types: list[str] | None = None
+
+
+class LocationResolveResponse(BaseModel):
+    results: list[ResolvedLocation]
+
+
+class PlaceDetails(BaseModel):
+    place_id: str
+    name: str | None = None
+    address: str | None = None
+    location: LatLng | None = None
+    rating: float | None = None
+    price_level: int | None = None
+    types: list[str] | None = None
+    phone: str | None = None
+    website: str | None = None
+    hours: list[str] | None = None
+    open_now: bool | None = None

package/skills/mcporter/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mcporter
+description: Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
+homepage: http://mcporter.dev
+metadata: {"nexus":{"emoji":"📦","requires":{"bins":["mcporter"]},"install":[{"id":"node","kind":"node","package":"mcporter","bins":["mcporter"],"label":"Install mcporter (node)"}]}}
+---
+
+# mcporter
+
+Use `mcporter` to work with MCP servers directly.
+
+Quick start
+- `mcporter list`
+- `mcporter list <server> --schema`
+- `mcporter call <server.tool> key=value`
+
+Call tools
+- Selector: `mcporter call linear.list_issues team=ENG limit:5`
+- Function syntax: `mcporter call "linear.create_issue(title: \"Bug\")"`
+- Full URL: `mcporter call https://api.example.com/mcp.fetch url:https://example.com`
+- Stdio: `mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com`
+- JSON payload: `mcporter call <server.tool> --args '{"limit":5}'`
+
+Auth + config
+- OAuth: `mcporter auth <server | url> [--reset]`
+- Config: `mcporter config list|get|add|remove|import|login|logout`
+
+Daemon
+- `mcporter daemon start|status|stop|restart`
+
+Codegen
+- CLI: `mcporter generate-cli --server <name>` or `--command <url>`
+- Inspect: `mcporter inspect-cli <path> [--json]`
+- TS: `mcporter emit-ts <server> --mode client|types`
+
+Notes
+- Config default: `./config/mcporter.json` (override with `--config`).
+- Prefer `--output json` for machine-readable results.

package/skills/model-usage/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: model-usage
+description: Use CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.
+metadata: {"nexus":{"emoji":"📊","os":["darwin"],"requires":{"bins":["codexbar"]},"install":[{"id":"brew-cask","kind":"brew","cask":"steipete/tap/codexbar","bins":["codexbar"],"label":"Install CodexBar (brew cask)"}]}}
+---
+
+# Model usage
+
+## Overview
+Get per-model usage cost from CodexBar's local cost logs. Supports "current model" (most recent daily entry) or "all models" summaries for Codex or Claude.
+
+TODO: add Linux CLI support guidance once CodexBar CLI install path is documented for Linux.
+
+## Quick start
+1) Fetch cost JSON via CodexBar CLI or pass a JSON file.
+2) Use the bundled script to summarize by model.
+
+```bash
+python {baseDir}/scripts/model_usage.py --provider codex --mode current
+python {baseDir}/scripts/model_usage.py --provider codex --mode all
+python {baseDir}/scripts/model_usage.py --provider claude --mode all --format json --pretty
+```
+
+## Current model logic
+- Uses the most recent daily row with `modelBreakdowns`.
+- Picks the model with the highest cost in that row.
+- Falls back to the last entry in `modelsUsed` when breakdowns are missing.
+- Override with `--model <name>` when you need a specific model.
+
+## Inputs
+- Default: runs `codexbar cost --format json --provider <codex|claude>`.
+- File or stdin:
+
+```bash
+codexbar cost --provider codex --format json > /tmp/cost.json
+python {baseDir}/scripts/model_usage.py --input /tmp/cost.json --mode all
+cat /tmp/cost.json | python {baseDir}/scripts/model_usage.py --input - --mode current
+```
+
+## Output
+- Text (default) or JSON (`--format json --pretty`).
+- Values are cost-only per model; tokens are not split by model in CodexBar output.
+
+## References
+- Read `references/codexbar-cli.md` for CLI flags and cost JSON fields.

package/skills/model-usage/references/codexbar-cli.md

@@ -0,0 +1,28 @@
+# CodexBar CLI quick ref (usage + cost)
+
+## Install
+- App: Preferences -> Advanced -> Install CLI
+- Repo: ./bin/install-codexbar-cli.sh
+
+## Commands
+- Usage snapshot (web/cli sources):
+  - codexbar usage --format json --pretty
+  - codexbar --provider all --format json
+- Local cost usage (Codex + Claude only):
+  - codexbar cost --format json --pretty
+  - codexbar cost --provider codex|claude --format json
+
+## Cost JSON fields
+The payload is an array (one per provider).
+- provider, source, updatedAt
+- sessionTokens, sessionCostUSD
+- last30DaysTokens, last30DaysCostUSD
+- daily[]: date, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, totalTokens, totalCost, modelsUsed, modelBreakdowns[]
+- modelBreakdowns[]: modelName, cost
+- totals: totalInputTokens, totalOutputTokens, cacheReadTokens, cacheCreationTokens, totalTokens, totalCost
+
+## Notes
+- Cost usage is local-only. It reads JSONL logs under:
+  - Codex: ~/.codex/sessions/**/*.jsonl
+  - Claude: ~/.config/claude/projects/**/*.jsonl or ~/.claude/projects/**/*.jsonl
+- If web usage is required (non-local), use codexbar usage (not cost).