Integrations

An integration gives agents tools for an outside service. The daemon makes every call on your credentials: no agent holds a token or key, and every call is on the run's page.

lucitra integration-add github             # uses your own gh login; stores no token
lucitra integration-add alpaca paper       # paper by default; `live` is its own install
lucitra integration-add market-data
lucitra integration-add research           # Finnhub, FRED and SEC EDGAR (SEC needs no key)
lucitra integration-add ntfy               # lets agents push to your verified ntfy channel
lucitra integrations                       # what is installed, which keys are set, who names which tools
lucitra integration-remove github          # takes its tools away from every agent

Who may call what

An agent calls a tool only where its access.yaml allows it, as integration:tool:

allow:
  tools:
    - github:*            # every GitHub tool except merge, approve and release
    - github:pr-merge     # those three only by name

Allowed tools run on their own unless a team policy lists them under gated:. A gated call waits for you in the Inbox. A gate can name an environment: alpaca:orders-create@live holds orders only while Alpaca is installed as live, so paper orders fill on their own.

Where keys come from

Keys stay where you already keep them. Lucitra keeps no copy, and listing which keys are set reads no value.

lucitra secret-source-add gcp my-project   # GCP Secret Manager, through your own gcloud login
lucitra secret-source-add env ./.env.local # or an env file; sources are tried in the order you add them
lucitra secret-sources

A key is looked up by its secret name in GCP. In an env file it is the same name in upper snake case, or the name the vendor's own docs use, so an existing .env works as it is:

Secret	Env file	Also accepted
`alpaca-paper-api-key-id` / `-secret`	`ALPACA_PAPER_API_KEY_ID` / `_SECRET`	`APCA_API_KEY_ID` / `APCA_API_SECRET_KEY`, unless `APCA_API_BASE_URL` is live
`alpaca-live-api-key-id` / `-secret`	`ALPACA_LIVE_API_KEY_ID` / `_SECRET`	the `APCA_*` pair, only beside `APCA_API_BASE_URL=https://api.alpaca.markets`
`market-data-finnhub-api-key`	`MARKET_DATA_FINNHUB_API_KEY`	`FINNHUB_API_KEY`
`research-fred-api-key`	`RESEARCH_FRED_API_KEY`	`FRED_API_KEY`

integration-add says which keys no source holds yet.

GitHub

Uses your own gh login. Reaches api.github.com and github.com.

Tool	Effect	What it does
`github:pr-list`	read	List open pull requests in this repository
`github:pr-read`	read	Read one pull request: title, body, state, review decision
`github:pr-files`	read	The files a pull request changes, and its diff
`github:issue-read`	read	Read one issue: title, body, state, labels
`github:pr-comment`	write	Comment on a pull request
`github:pr-create`	push	Push this worktree's branch and open a pull request from it
`github:pr-approve`	irreversible	Approve a pull request
`github:pr-merge`	irreversible	Squash-merge a pull request
`github:release-create`	irreversible	Create a release from a tag

Alpaca

A brokerage account. Installs as paper or live, each with its own key pair. Reaches paper-api.alpaca.markets and api.alpaca.markets.

Tool	Effect	What it does
`alpaca:portfolio-balance`	read	The account: equity, cash, buying power
`alpaca:portfolio-positions`	read	Every open position
`alpaca:orders-list`	read	Open orders
`alpaca:fills-list`	read	Recent fills
`alpaca:orders-cancel`	write	Cancel one open order
`alpaca:orders-create`	irreversible	Place an order
`alpaca:orders-amend`	irreversible	Change an open order's quantity or limit price

Market data

Quotes from Finnhub; history from Alpaca's market data, on the paper keys unless Alpaca is installed live. Reaches finnhub.io and data.alpaca.markets.

Tool	Effect	What it does
`market-data:quote`	read	The latest quote for one ticker
`market-data:batch-quote`	read	Latest quotes for several tickers
`market-data:history`	read	Daily bars for one ticker

Research

Finnhub, FRED and SEC EDGAR. SEC needs no key. Reaches finnhub.io, api.stlouisfed.org, data.sec.gov, www.sec.gov and data.alpaca.markets.

Tool	Effect	What it does
`research:equity-quote`	read	The latest quote for one ticker
`research:equity-history`	read	Daily bars for one ticker
`research:fred-series`	read	Observations of one FRED series, such as DGS10 or CPIAUCSL
`research:news-search`	read	Recent company news for one ticker
`research:sec-filings`	read	Recent SEC filings for one ticker

ntfy

Lets an agent granted ntfy:notify push to your verified ntfy channels, at most 20 an hour per team. Never SMS or WhatsApp. Reaches ntfy.sh.

Tool	Effect	What it does
`ntfy:notify`	write	Send you a push notification, for news you would want now

Trading limits

Every order through a brokerage integration is held to limits that scale with the account, whatever the team: at most 2% of the account per order, and no new orders once the day's loss reaches 5%. Change them with lucitra trading-limits and lucitra trading-limit alpaca <key> <value|default|none>, or in the app under Settings → Trading limits, which can only tighten one.

A team's policy can add its own. The most conservative of yours and the policy's applies, on every environment, whether or not the order was gated:

limits:
  alpaca:
    max_order_pct: 1              # of the account's equity
    max_order_dollars: 500
    max_orders_per_day: 5
    daily_max_loss_dollars: 100
    symbols: [SPY, QQQ, AAPL]

An order whose size cannot be worked out, or an account whose size cannot be read, is refused while a cap needs it. A refusal is a row in the run's record, with the reason. A limit the policy does not write is not enforced.