manigent-server 0.1.0__py3-none-any.whl

manigent/_catalog/skills/ib/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ib
+description: >
+  Interactive Brokers — STRICTLY READ-ONLY fetch of positions, cost basis, PnL,
+  current prices, historic prices, and news for US equities and bonds. Invoked
+  via `manigent ib {positions,cost-basis,pnl,price,history,news-providers,news,
+  news-article,doctor}`. There is NO order/buy/sell/cancel path — this skill can
+  never trade. Requires a human-operated TWS / IB Gateway logged in out-of-band;
+  connection coordinates (host/port/clientId/account) resolve from
+  `$MANIGENT_AGENT_DIR/skill-hub/configs/ib.json`. Market data is LIVE by
+  default — delayed data is only served under `--allow-delayed` and is tagged.
+---
+
+# /manigent:ib
+
+Read-only Interactive Brokers access via the `manigent ib` CLI. Use it to
+answer questions about the account's holdings and market data for **US equities
+and bonds**. It cannot place, modify, or cancel orders — by design.
+
+## Step 0 — Preflight
+
+A human operator must be running **IB Gateway** (recommended, headless) or TWS,
+logged in, with the **API enabled** and, for defence in depth, **Read-Only API**
+turned on (Gateway/TWS → Global Config → API → Settings). Our code never sees
+IBKR credentials — only the socket. Config resolves from
+`$MANIGENT_AGENT_DIR/skill-hub/configs/ib.json` (host/port/clientId/account);
+if it's missing, defaults to a localhost Gateway on port 4001.
+
+Run `manigent ib doctor` first when unsure — it reports connectivity, the
+connected account id, **paper vs live**, read-only status, and which news
+providers are subscribed, **without returning any market data**. A wrong port
+(paper vs live) yields real-looking but wrong data, so verify `account_kind`.
+
+## Step 1 — Pick the subcommand
+
+| Intent | Command |
+|---|---|
+| "what do I hold?" | `manigent ib positions` |
+| Cost basis of holdings | `manigent ib cost-basis` |
+| Profit/loss | `manigent ib pnl [--conid 265598 ...]` |
+| Current price (equity) | `manigent ib price AAPL` |
+| Current price (bond) | `manigent ib price 037833100 --sec-type BOND` |
+| Price history | `manigent ib history AAPL --duration "6 M" --bar-size "1 day"` |
+| Bond price history | `manigent ib history 912828YK0 --sec-type BOND --what YIELD` |
+| Which news providers? | `manigent ib news-providers` |
+| Headlines for a name | `manigent ib news AAPL --lookback-days 14 [--provider BRFG]` |
+| Full article body | `manigent ib news-article BRFG <articleId>` |
+| Setup self-check | `manigent ib doctor` |
+
+`--config` self-resolves; you rarely pass it.
+
+## Step 2 — Equities vs bonds
+
+- **Equity**: pass the ticker symbol, `--sec-type STK` (the default).
+- **Bond**: pass the **CUSIP** and `--sec-type BOND`. The bond is resolved
+  CUSIP → conId and must match exactly one instrument (an ambiguous CUSIP is an
+  error, not a guess). Bond prices are quoted **clean (percent of par)**; the
+  payload reports `accrued_interest` as a **separate field**, never folded into
+  the price, plus a `bond` block with `clean_price` / `dirty_price` /
+  `market_value_clean` / `market_value_dirty`.
+
+## Step 3 — Live vs delayed data
+
+Prices and history are **LIVE by default**. If the account lacks a live
+subscription, the command **errors** (`{"error":"not_subscribed", ...}`) rather
+than quietly returning delayed or empty data. Only add `--allow-delayed` when
+the user explicitly accepts delayed data; the returned payload is then tagged
+`"data_type": "delayed"` so you can flag it to the user. Never present delayed
+data as live.
+
+## Step 4 — Errors are structured, act on them
+
+Failures print JSON to stderr and exit non-zero — never a silent empty success:
+
+| `error` | Meaning | What to tell the user |
+|---|---|---|
+| `not_subscribed` | Missing paid market-data / news subscription | Name the instrument + missing entitlement; suggest `manigent ib doctor`. |
+| `contract_resolution` | Symbol/CUSIP didn't resolve to one instrument | Ask for a correct symbol/CUSIP. |
+| `pacing` | IB rate limit; carries `retry_after` seconds | Wait `retry_after`s and retry (pacing is persisted on disk across calls). |
+| `connection` | Gateway down / logged out / wrong port | Ask the operator to (re)start + log into IB Gateway. |
+
+## Guardrails
+
+- **Read-only, always.** There is no trading subcommand and the code carries no
+  order symbol (CI-enforced by `tests/test_ib_readonly_guard.py`). Do not ask
+  this skill to buy, sell, or cancel — it cannot, and won't be extended to.
+- **Single account** this milestone. If the login manages several accounts,
+  pass `--account`; otherwise the command errors rather than guessing.
+- Treat the account id as sensitive — don't echo it into shared chat files.

manigent/_catalog/skills/ib/starter_config.jsonc

@@ -0,0 +1,35 @@
+{
+  // Interactive Brokers connection coordinates — CONNECTION ONLY.
+  // This file carries NO credentials. Your IBKR username / password / 2FA live
+  // solely inside the human-operated TWS / IB Gateway you connect to; nothing
+  // here is a secret and nothing here is logged.
+  //
+  // Resolved from $MANIGENT_AGENT_DIR/skill-hub/configs/ib.json. A missing file
+  // falls back to a localhost IB Gateway (live) on port 4001.
+
+  // Host running TWS / IB Gateway. Keep it on the runner (127.0.0.1) so the API
+  // socket is never exposed off-box.
+  "host": "127.0.0.1",
+
+  // API port. IB Gateway: 4001 live / 4002 paper. TWS: 7496 live / 7497 paper.
+  // Pointing at the paper port yields real-looking but wrong data — verify with
+  // `manigent ib doctor` (it reports paper vs live).
+  "port": 4001,
+
+  // A dedicated, unique client id for this read-only client so it doesn't
+  // collide with a human TWS session or another integration.
+  "client_id": 17,
+
+  // Optional. Disambiguates the account to query. Leave "" to use the login's
+  // sole account; if the login manages several, set this (single-account scope
+  // this milestone). Treated as sensitive — never echoed into shared chat.
+  "account": "",
+
+  // Default market-data type: 1=live, 2=frozen, 3=delayed, 4=delayed-frozen.
+  // Leave at 1 (LIVE). Delayed data is otherwise reachable only via the
+  // per-call --allow-delayed flag, which tags the payload data_type=delayed.
+  "market_data_type": 1,
+
+  // Bounded connect timeout (seconds).
+  "connect_timeout_s": 15
+}

manigent/_catalog/skills/mailbox/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: mailbox
+description: >
+  IMAP+SMTP mailbox (search / read / attachment / send). Provider-agnostic —
+  works with Gmail (app password), iCloud, Fastmail, Outlook, ProtonMail
+  Bridge, self-hosted Dovecot/Postfix. Invoked via
+  `manigent mailbox {list-folders,search,get,attachment,send}`. No OAuth —
+  credentials via `${VAR}` env vars referenced from
+  `$MANIGENT_AGENT_DIR/skill-hub/configs/mailbox.json`.
+---
+
+# /manigent:mailbox
+
+IMAP + SMTP mailbox via the `manigent mailbox` CLI.
+
+## Step 0 — Preflight
+
+Config at `$MANIGENT_AGENT_DIR/skill-hub/configs/mailbox.json` with an
+`imap` block (and an optional `smtp` block for sending). Env vars referenced
+as `${VAR}` must be exported on the runner. Missing config ⇒ reply "Open Agent
+Settings → Skills → mailbox → Configure first."
+
+## Step 1 — Pick the subcommand
+
+| Intent | Command |
+|---|---|
+| List folders | `manigent mailbox list-folders` |
+| Search | `manigent mailbox search "from:alice@x.com subject:invoice" --folder INBOX --max 20` |
+| Read one (headers + text/html body + attachment list) | `manigent mailbox get <UID>` |
+| Attachment | `manigent mailbox attachment <UID> <part-id> --out path.pdf` |
+| Send | `manigent mailbox send --to ... --subject "..." --body -` |
+
+Search mini-DSL: `from:`, `to:`, `subject:`, `since:YYYY-MM-DD`,
+`before:`, bare flags `unseen` / `seen` / `flagged` / `answered`, bare
+words → BODY substring.
+
+## Step 2 — Send safely
+
+Always reflect the user's intent back before sending. Pipe long bodies
+via stdin: `--body -`.
+
+## Step 3 — Fetching mail on a schedule
+
+These commands only fetch (and send). If your SOP has you pull mail regularly,
+where you store it, how you deduplicate it (`get` returns `message_id_hash`,
+derived from the RFC822 Message-ID), and how you track what you already fetched
+(e.g. a `since:` search term from your last run) is up to that SOP.

manigent/_catalog/skills/mailbox/starter_config.jsonc

@@ -0,0 +1,38 @@
+{
+  // IMAP+SMTP credentials. Defaulted to Gmail.
+  //
+  // Gmail setup:
+  //   1. Enable 2-Factor Authentication on your Google Account.
+  //   2. Generate an App Password at https://myaccount.google.com/apppasswords
+  //      (the regular account password won't work — Google blocks IMAP/SMTP
+  //      plain-password auth).
+  //   3. On the runner, export both env vars before `manigent start`:
+  //        export MAILBOX_USERNAME="you@gmail.com"
+  //        export MAILBOX_PASSWORD="xxxx xxxx xxxx xxxx"   # the app password
+  //
+  // Other providers — change imap.host / smtp.host (see mcps/mailbox/README.md):
+  //   iCloud:    imap.mail.me.com  / smtp.mail.me.com   (port 587, starttls;
+  //              app-specific password from https://appleid.apple.com/account/manage)
+  //   Fastmail:  imap.fastmail.com / smtp.fastmail.com  (app password from
+  //              https://www.fastmail.com/settings/security/devicepw)
+  //   Outlook:   outlook.office365.com / smtp.office365.com
+  //
+  // The `smtp` block is optional. Drop it if this agent only reads mail;
+  // `send_message` will then raise a clear error.
+
+  "imap": {
+    "host": "imap.gmail.com",
+    "port": 993,
+    "ssl": true,
+    "username": "${MAILBOX_USERNAME}",
+    "password": "${MAILBOX_PASSWORD}"
+  },
+  "smtp": {
+    "host": "smtp.gmail.com",
+    "port": 587,
+    "starttls": true,
+    "username": "${MAILBOX_USERNAME}",
+    "password": "${MAILBOX_PASSWORD}",
+    "from": "${MAILBOX_USERNAME}"
+  }
+}

manigent/_catalog/skills/media/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: media
+description: >
+  Generate media from a text prompt — images, speech audio, or video — and save
+  the file to disk. Images also support image-to-image editing/compositing via a
+  repeatable `--input-image` (edit a photo with a prompt, or swap a background
+  using a second image). One CLI, three subcommands:
+  `manigent media image  --prompt "..." [--size ...] [--quality ...] [--input-image PATH ...]`,
+  `manigent media audio  --prompt "..." [--voice ...] [--format ...]`,
+  `manigent media video  --model owner/name --prompt "..." [--duration ...] [--aspect-ratio ...] [--input-image PATH]`.
+  Backend is chosen by `--provider` (or the per-agent config) — image: openai /
+  gemini / nano-banana; audio: openai / elevenlabs / gemini; video: replicate /
+  fal (gateways that route to Veo, Kling, etc.). Settings resolve in the order
+  flag > config > env var > default, so you can run from flags alone (e.g.
+  `--provider openai --api-key $KEY`) when keys are in the runner env. Each call
+  prints `{media_path, media_type, provider, model, ...}` — the file lands on
+  disk; share it with `update_file`. No OAuth — keys come from `--api-key`, the
+  config (Agent Settings → Skills → media → Configure), or env vars.
+---
+
+# /manigent:media
+
+The agent profile decides *when* media is the right output; this skill is *how*
+— a Bash call to `manigent media <image|audio|video>`. The returned
+`media_path` is an absolute filesystem path; hand it to `update_file` to surface
+it in chat (the web UI plays audio/video inline and shows images inline).
+
+## Step 1 — Build a strong prompt
+
+Embellish a one-liner with the cues that matter for the modality before calling:
+- **image** — medium, lighting, composition, subject specifics.
+- **audio (TTS)** — write the exact words to speak; pick a `--voice`.
+- **video** — describe motion, shot, pacing; keep clips short.
+
+## Step 2 — Invoke
+
+```bash
+# Image (defaults to provider openai / gpt-image-2)
+manigent media image --prompt "rustic chardonnay bottle, soft window light, top-down"
+manigent media image --provider gemini --prompt "..." --size 16:9
+
+# Image-to-image: edit one photo with a prompt (openai or nano-banana)
+manigent media image --input-image /path/bottle.png --prompt "make the sky stormy, keep the bottle"
+# Background swap: subject image first, background image second (nano-banana recommended)
+manigent media image --provider nano-banana \
+  --input-image /path/subject.png --input-image /path/beach.png \
+  --prompt "place the subject from image 1 onto the beach in image 2"
+
+# Speech audio
+manigent media audio --prompt "Welcome to the tasting room." --voice alloy
+manigent media audio --provider elevenlabs --prompt-file /tmp/script.txt
+
+# Video (provider replicate/fal need a --model slug; runs take minutes)
+manigent media video --model google/veo-3 --prompt "slow dolly across a vineyard at golden hour" --aspect-ratio 16:9
+manigent media video --provider fal --model fal-ai/kling-video/v1/standard/text-to-video --prompt "..." --input-image /path/to/still.png
+```
+
+Long prompts: write to a tmpfile and pass `--prompt-file <path>`, or stream via
+`--prompt -`. Flags override the per-agent config; omit them to fall back to it.
+
+Modality flags:
+- **image** `--size` (openai px `1024x1024|1024x1536|1536x1024|2048x2048|2048x3072|3072x2048|auto`; gemini
+  aspect `1:1|9:16|16:9|3:4|4:3`; ignored for nano-banana) and `--quality`
+  (openai only: `auto|low|medium|high`).
+- **image editing** `--input-image PATH` (repeatable) turns `media image` into
+  image-to-image: one input edits that photo per the prompt; two+ inputs
+  composite them (first is the subject, later ones are background/reference).
+  Works with `openai` (gpt-image-2) and `nano-banana` only — **not** `gemini`
+  (Imagen), which errors with guidance. Prefer `nano-banana` for background
+  swaps / multi-image compositing. On the openai path `--size`/`--quality` still
+  apply (output aspect follows the request, not the input); nano-banana ignores
+  them. No masks — editing is prompt-driven.
+- **audio** `--voice` and `--format` (openai: `mp3|wav|opus|aac|flac`).
+- **video** `--duration`, `--aspect-ratio`, `--input-image` (image→video). These
+  are model-dependent — only pass what the chosen model accepts.
+
+## Step 3 — Use the result
+
+The JSON output's `media_path` (also `image_path`/`audio_path`/`video_path`) is
+an absolute path. Pass it to `update_file` to share it in chat, or to other
+tools (Pillow overlay, google-drive-write upload). The bytes are already on disk
+— don't re-encode.
+
+**Keep media small.** The server caps uploaded files (default ~25 MB); generate
+short clips / compressed output so `update_file` doesn't get rejected with a
+413.
+
+## Step 4 — Errors
+
+Unsupported `--provider`, a missing api_key (no flag, no config, no env var), or
+a provider/model error all surface as `exit 1` with a clear message — relay it
+verbatim. Video `replicate`/`fal` require a `--model` slug; without one you'll
+get a clear config error.

manigent/_catalog/skills/media/starter_config.jsonc

@@ -0,0 +1,63 @@
+{
+  // media — generate image / audio / video and save the file to disk. One
+  // section per modality. Every value here is a DEFAULT: a matching CLI flag
+  // (--provider / --model / --api-key / --output-dir / --size / --voice / ...)
+  // overrides it, and an unset api_key falls back to the provider's env var,
+  // so an agent can also run from flags + env with no config at all.
+  //
+  // api_key — inline a literal OR a ${VAR} placeholder resolved from runner
+  //           env. Conventional env vars (set before `manigent start`):
+  //             openai      → ${OPENAI_API_KEY}
+  //             gemini /
+  //             nano-banana → ${GEMINI_API_KEY}
+  //             elevenlabs  → ${ELEVENLABS_API_KEY}
+  //             replicate   → ${REPLICATE_API_TOKEN}
+  //             fal         → ${FAL_KEY}
+  // output_dir — absolute path the files land in; ${MANIGENT_AGENT_DIR}
+  //              picks the per-agent location. Defaults to
+  //              ${MANIGENT_AGENT_DIR}/media/<modality> when omitted.
+
+  "image": {
+    // provider: "openai" (gpt-image-2) | "gemini" (Imagen) | "nano-banana".
+    // Image-to-image editing (--input-image, repeatable) works with openai and
+    // nano-banana only; nano-banana is stronger for background swaps / compositing.
+    "provider": "openai",
+    "api_key": "${OPENAI_API_KEY}",
+    "model": "gpt-image-2",
+    // openai px: 1024x1024 | 1024x1536 | 1536x1024 | 2048x2048 |
+    //            2048x3072 | 3072x2048 (2K) | auto
+    // gemini aspect: 1:1 | 9:16 | 16:9 | 3:4 | 4:3 ; nano-banana ignores size.
+    "default_size": "1024x1024",
+    // openai only: auto | low | medium | high
+    "default_quality": "auto",
+    "output_dir": "${MANIGENT_AGENT_DIR}/media/image",
+    "timeout_seconds": 120
+  },
+
+  "audio": {
+    // provider: "openai" (TTS) | "elevenlabs" | "gemini" (TTS).
+    "provider": "openai",
+    "api_key": "${OPENAI_API_KEY}",
+    "model": "gpt-4o-mini-tts",
+    // openai voices: alloy, echo, fable, onyx, nova, shimmer, ...
+    // elevenlabs: a voice_id ; gemini: Kore, Puck, ...
+    "voice": "alloy",
+    // openai output format: mp3 | wav | opus | aac | flac
+    "format": "mp3",
+    "output_dir": "${MANIGENT_AGENT_DIR}/media/audio",
+    "timeout_seconds": 120
+  },
+
+  "video": {
+    // provider: "replicate" (owner/name slug, e.g. google/veo-3) | "fal"
+    // (fal-ai/... slug). Both are gateways routing to Veo / Kling / etc.
+    "provider": "replicate",
+    "api_key": "${REPLICATE_API_TOKEN}",
+    // No default model — set the slug here or pass --model per call.
+    "model": "",
+    "output_dir": "${MANIGENT_AGENT_DIR}/media/video",
+    // Video runs take minutes; keep under the runner's 1800s kill window.
+    "timeout_seconds": 900,
+    "poll_interval_seconds": 5
+  }
+}

manigent/_catalog/skills/osxphotos/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: osxphotos
+description: >
+  macOS Photos library (Photos.app + iCloud Photo Library) — read-only
+  metadata + paths, plus JPEG export for vision Read. Invoked via
+  `manigent osxphotos {list-albums,list-photos,export,export-jpeg}`. macOS
+  only; requires `osxphotos` on the runner and Full Disk Access to the Python
+  interpreter. No OAuth, no config.
+---
+
+# /manigent:osxphotos
+
+macOS Photos library access via the `manigent osxphotos` CLI.
+
+## Step 0 — Preflight
+
+macOS + `pip install osxphotos` + Full Disk Access for Python.
+
+## Step 1 — Pick the subcommand
+
+| Intent | Command |
+|---|---|
+| Albums + photo counts | `manigent osxphotos list-albums` |
+| Photos in album | `manigent osxphotos list-photos --album "2025" --limit 50` |
+| Force-download iCloud-only | `manigent osxphotos export <UUID> --dest /tmp/photo` |
+| Transcode for vision Read | `manigent osxphotos export-jpeg <UUID> --dest /tmp/photo` |
+
+## Step 2 — Image bytes (vision pipelines)
+
+`list-photos` returns paths but not bytes (`path` is null for iCloud-only
+photos). Either:
+1. Call `export-jpeg <UUID>` (default `--max-dim 1200 --quality 65` yields
+   ~120 KB — under Claude Code's 256 KB Read cap), then Read the JPEG.
+2. Call `export <UUID>` for original-quality bytes (likely too big to Read).
+
+## Step 3 — Fetching photos on a schedule
+
+These commands only fetch. If your SOP has you pull photo metadata regularly,
+where you store it, how you deduplicate it (`uuid` is stable), and how you
+track what you already fetched (e.g. `date_added` — when the photo entered the
+library, unlike `date`, the EXIF capture time) is up to that SOP.