Uniform plugin contract
Facts first, then a handle, then judgment.
Every implemented plugin is supposed to expose the same interaction shape. The first reply stays compact; drill-down recovers the source leaves. The model owns interpretation unless a cited contract assigns a purely mechanical choice to the plugin.
Exact input identity
Every tool call names the track, listing or instrument, scope, time basis, requested operation, and instruction receipt. An ambiguous ticker is a failure, not a guess.
Typed information states
Known, unknown, not obtained, unavailable, conflicting, decode failure, unperformed, truncated, cancelled, and externally blocked facts stay distinct. Unknown stays unknown.
Compact first response
The first model-visible reply is targeted below 500 tokens: scope, coverage, important limitations, a stable content-bound handle, and neutral available operations.
Bounded drill-down
Ask for the handle to recover original lexemes, source leaves, formula trees, alternatives, and correction lineage. Details used only by the renderer are not model context.
No silent repair
Budgets, pagination, truncation, and cancellation are explicit. Failure never falls back to another provider, track, date, filing, or persisted namespace.
LLM owns judgment
Plugins expose facts, calculations, read-only state, and non-executing effects. Interpretation, thresholds, recommendations, authorization, and every market action stay with the user and the model.
Five context layers
Every conclusion should be traceable down the stack.
Validated identity
Track, MIC or venue, board, listing, share class, status, currency, timezone, and effective date—never just an ambiguous ticker.
Canonical observation
The source value plus as-of and retrieval time, freshness, unit, adjustment, quality, and entitlement. Unknown fields remain unknown.
Evidence and provenance
Content receipts, provider and document identifiers, source versions, hashes, correction lineage, gaps, duplicates, and conflicts.
Typed calculation
Inputs, formula or expression tree, period and filing coherence, output unit, rounding assumptions, and complete source leaves.
Decision record
A plan, scenario, thesis, replay, portfolio change, or journal entry with its assumptions and source receipts—not an executable instruction.
Canonical observation
The value travels with its caveats.
Provider-backed facts are normalized into an observation envelope. Individual tools add domain fields, but must not flatten away source control or invent unavailable metadata.
{
"track": "cn",
"identity": { "mic": "XSHG", "symbol": "600519" },
"value": { "close": "1438.00", "currency": "CNY" },
"source": "selected-provider-id",
"as_of": "2026-08-11",
"retrieved_at": "caller-clock timestamp",
"freshness": "completed_daily",
"adjustment": "explicit policy",
"quality": ["provider_observation"],
"entitlement": "declared or unknown",
"receipt": "content-bound identifier"
}Personal watchlist
Remember your picks across chats.
Mention the stocks you follow. Sparkles gives Pi an option to ask, “Shall I remember these picks across chats?” Accept in conversation to turn on a private local watchlist. Storage and checks stay off until you accept; saving picks does not start polling.
My picks are CN 600519 and CN 600000. What can Sparkles do with my watchlist?
After accepting, ask to show your saved picks in a later chat. The default store is ~/.pi-sparkles-watchlist. CN, HK and US identities stay separately labelled, and credentials are never saved with the picks.
Show my saved watchlist. Review my core watchlist once using Eastmoney A-share quotes, and show the source receipts and any unknown facts.
CN A-share reviews use the explicitly selected Eastmoney source and your runtime AGENT_CONTACT. HK and US picks can be remembered; their review acquisition remains track_partial. The model interprets the observed facts.
For recurring reviews, choose an interval and a bounded number of checks explicitly. Checks run while Pi is open and owns the store. Pi Durable retains receipts and resumes unfinished work after a restart; an interrupted source read remains unknown without automatic refetch. Ask to inspect review results, cancel a schedule or disable persistence. Disabling retains your saved data.
DSH keeps a separate watchlist for each agent and restores it from that agent's persisted session log. The Pi Durable store and review scheduler are specific to Pi. DSH retains its own lifecycle and session-scoped state.
Ask for the audit view
Make hidden assumptions visible before analysis.
Before answering, show the exact listing identity, track, selected provider, as-of and retrieval times, freshness, units, adjustment policy, quality labels, entitlement or rights limitations, calendar and rule versions, gaps, conflicts, and receipt identifiers. Keep unknown facts unknown.
Model content versus terminal display
Complete inputs can stay visually quiet.
CN, HK, and US daily history/OHLCV acquisition tools send every bounded exact row to the model as compact CSV, alongside the track, provider, identity, currency, adjustment, retrieval time, and receipt identifier needed to interpret it. This lets the model construct SMA, RSI, and ATR inputs without claiming that the daily values are unavailable. Compact indicator results send the latest and requested prior numbers to the model while the host UI stays concise; exact receipt handles remain available without echoing the full series again. projection.priorOffset is one-based from 1 through 2,000, newest calculated value first, so 1 selects the newest value and 0 is invalid. Intermediate projection is reserved for explicit full-series drill-down.
For indicator input basis, raw, split_adjusted, dividend_adjusted, and total_return omit label and instructionRef entirely—never send null. provider_defined requires only a label; llm_projection requires both fields. Ordinary history handoffs omit the top-level instructionRef unless a real retained SHA-256 reference already exists.
Buy-now, sell-timing, entry, exit, stop, and target questions are evidence-seeking prompts rather than permission to answer from general knowledge. Unless you explicitly ask for education only or decline fresh lookup, the agent should use the active track's read-only quote and bounded OHLCV tools, calculate relevant installed indicators, and then give a conditional scenario. Trade-plan calculations require their exact risk inputs, and order-path simulation requires an exact proposed order; neither should block ordinary market-evidence collection.
Pi shows only the first summary line while an ordinary tool result is collapsed. Expanding it reveals the exact fallback. For chart_ohlcv, Pi renders a width-proportional ASCII chart inline in that result—never an overlay, image, or file. The complete structured result and receipts remain in tool details; model-required values remain in textual content.
The DSH bridge normalizes the same tool result to canonical JSON and renders safe ContentBlock[] output. For chart_ohlcv, bounded presentation metadata drives a keyed responsive SVG card inline in the transcript, with pan, zoom, and Reset controls. It is not an attachment or overlay, and exact text plus structured details remain the controlling fallback.
Fetch one bounded daily OHLCV series for the active track. Confirm that the CSV rows are readable, state the exact adjustment and currency, then calculate SMA, RSI, and ATR from those rows. Do not claim the values are unavailable and do not infer unknown volume or calendar facts.
Deliberately excluded
Some information must never reach the model.
- Environment values, API tokens, secret keys, cookies, and brokerage credentials.
- Unbounded raw account exports or private documents that have not passed a reviewed import boundary.
- Write-capable broker authority, executable order instructions, or order-mutation handles.
- Facts silently borrowed from another provider, market track, date, filing, or persisted namespace.
- Unsupported certainty about rights, service level, correction coverage, completeness, or authenticity.