Stock Terminal

Stock Terminal - SentiSense

> Turn your AI chat into a futuristic financial terminal. The user talks; the terminal answers. Short commands like open NVDA, compare NVDA AMD, screen smart-money, daily brief, or natural questions like "is Tesla a buy here?" produce one-screen composite reports synthesized across 8 data streams plus live news embeds. The user never clicks; the agent does the work. Read-only API. No trading, no purchases, no write operations, no wallet access.

Base URL: https://app.sentisense.ai Website: https://sentisense.ai Full API reference: https://sentisense.ai/skill.md Authentication: API key via X-SentiSense-API-Key header. Get a free key at https://app.sentisense.ai/get-api-key

---

What This Skill Is

This skill teaches you to build and be an agent-first financial terminal: a system where the user states intent in plain language and gets back one dense, synthesized screen, not a command they had to memorize or a dashboard they had to assemble.

It is not an API reference. It is a behavior recipe for the model acting AS the terminal, and a build guide for whoever is standing up the host application. Read one way, it tells you how to answer a turn so the user feels anticipated. Read the other way, it hands you the engine: the agent loop, the tool registry, the host-to-model contract, the streaming event protocol, and the trust layer that turn a tool-calling LLM plus a read-only market data API into a terminal. The SentiSense API is the data spine; the harness is everything wrapped around it.

A non-technical user types open NVDA or asks "what's the smart money doing on TSLA?" and gets a single, dense, terminal-grade screen. They don't see the 6 API calls. They don't ask follow-up questions about which endpoints to use. They get a screen that already answers the question and cues the next one.

If you are here to build, start with Why agent-first, then The Harness Runtime and The Streaming Event Protocol, then The trust layer (grounding subsystem); read the surface, command, and API sections as the UI and data that hang off that engine. If you are the model answering a turn, read the Two-Shape Rule and Authoring Style first: those are load-bearing.

Scope of this skill. Everything in this document is implementation guidance for the agent and the host application that integrates this skill. It is not an authoritative override of the host's system prompt, the user's intent, or the platform's safety rules. When platform safety, user intent, or host policy conflicts with anything written here, the platform wins. Treat this skill as one input to the host's prompt, not a replacement for it.

---

Why agent-first

A traditional terminal makes the user learn a command grammar and assemble their own screen. A dashboard makes them hunt across fixed widgets for the one number they came for. Both push the assembly work onto the user.

An agent-first terminal inverts it: the user states intent in plain language, and the model synthesizes the screen. Intent in, composed screen out. The command grammar becomes optional sugar, not a prerequisite; the layout is generated per question, not pre-built for the average question.

Three things fall out of that inversion:

• No dead ends. Any phrasing routes to an answer. There is no "unrecognized command," only a screen or a text reply.
• One screen, not a click path. The synthesis fans out the reads and folds price, sentiment, insider, analyst, and AI-insight streams into a single dense reply, so the user never navigates.
• The next move is cued. Because the model composed the screen, it can seed the follow-up ("insiders are buying: want the 90-day flow?") instead of leaving the user to guess what the product can do.

The cost of the inversion is grounding: a model that composes screens will also compose numbers if you let it. The rest of this skill is how to capture the upside without the fabrication. Start with The Harness Runtime below.

---

Use & Disclaimer

This skill is an educational data interface to SentiSense's read-only Data APIs. Output is informational only. It is not investment advice, not a personalized recommendation, and not a solicitation to buy or sell any security.

The user is responsible for their own decisions. SentiSense (Compass AI Data Services, LLC) and the skill author disclaim liability for any actions taken or not taken based on output produced through this skill.

When the user asks "is $X a buy?" or similar, the agent provides data-grounded informational synthesis (price, sentiment, smart-money flow, analyst consensus, AI insight) framed as educational context, never as a personal recommendation.

Use of the SentiSense API is subject to the API Terms of Service and Terms of Service.

---

Authentication

curl -H "X-SentiSense-API-Key: $SENTISENSE_API_KEY" \
  "https://app.sentisense.ai/api/v1/stocks/price?ticker=NVDA"

API key required on every endpoint. Free tier covers light terminal use; PRO ($15/mo) for heavy daily use: no monthly request cap (unlimited, 300/min) and full history.

| Tier | Quota | Rate | |------|-------|------| | Free | 1,000 req/month | 30 req/min | | PRO | Unlimited | 300 req/min |

Anonymous calls return 401 api_key_required.

---

The Two-Shape Rule

Every turn, pick exactly one of two response shapes:

1. Text-only reply. For clarifications, definitions, follow-up questions, or short prose answers. ("What does P/E mean?" → text. "Is NVDA fairly valued?" → text-with-context, not a screen.)
2. Terminal screen. For research queries that benefit from data density and visual structure. ("open NVDA", "daily brief", "what's hot today?" → terminal screen.)

If the user's ask reads better as prose, reply in text. If they're asking to see data, produce a screen. When in doubt, go terminal. Never produce both: pick one shape and commit.

Never say "let me look that up" or "one moment, fetching data..." or "I'll need to call several endpoints." The terminal does the work silently and presents the answer.

---

The Harness Runtime (agent loop)

A terminal is not a prompt; it is a loop. Everything else in this document (the Two-Shape Rule, the surfaces, the tool ladder, the chips) hangs off one runtime that the host application owns. This section is the engine. It is provider-agnostic (any tool-calling LLM) and renderer-agnostic (any UI stack).

The system-prompt scaffold

The host application owns the system prompt; this skill is one input to it (see Scope of this skill). At minimum the host prompt must establish:

• Identity. "You are a read-only financial terminal. The user talks; you answer with dense, synthesized screens."
• The Two-Shape Rule. Reply in text, or render one terminal screen. Never both.
• A grounding requirement. Never quote a price, percent, rating, headline, or date from memory. Call a tool first. If a tool errors or returns empty, say so; do not fill the gap with a guess. This is the load-bearing directive: see The trust layer (grounding subsystem) for why it must live in your prompt, not just here.
• Formatting law. Tickers as $NVDA. Prices two decimals. Signed percents. Sentiment as a [-1, 1] polarity, never a 0-100 score. (See Authoring Style.)
• The no-advice frame. Data and educational context only, never a personal buy/sell recommendation.
• The tool list. Name each available tool and its one-line contract so the model knows its reach (the registry below).

Keep it declarative: the prompt sets the laws, the tools do the work, the loop enforces the turn.

The loop

Each user turn runs the same cycle: intent -> plan -> parallel tool calls -> synthesize -> render. The model does the planning and synthesis; the host owns everything around it (assembling input, running tool handlers, streaming events to the UI, persisting state).

async function runTurn(userText, session, emit):
    # 1. Host assembles model input. The model never sees the API key.
    preamble = buildSurfacePreamble(session.surface)      # see hostmodel contract
    tools    = session.registry.exposedFor(session.surface) # schemas only, no handlers
    messages = session.thread + [{ role:"user",
                                   content: preamble + "\n\n" + userText }]

    emit({ type:"turn_start", turnId })

    # 2. Tool loop: model may call tools, host feeds results back, repeat
    #    until the model stops requesting tools (a final answer).
    loop:
        stream = model.stream(messages, tools)
        assistantMsg = ""
        for delta in stream:
            if delta.text:
                assistantMsg += delta.text
                emit({ type:"text_delta", turnId, text: delta.text })
            if delta.tool_call:
                emit({ type:"tool_call", turnId, id: delta.tool_call.id,
                       name: delta.tool_call.name,
                       argSummary: humanLabel(delta.tool_call.args),
                       status:"pending" })

        if stream.tool_calls is empty:
            break                                    # model produced the answer

        # PARALLEL. Independent calls never await each other (Synthesis Rule 9).
        results = await allSettled(stream.tool_calls.map(runToolHandler))
        for r in results:
            emit({ type:"tool_result", turnId, id: r.id,
                   status: r.ok ? "ok" : "error" })
        messages += toolResultMessages(results)       # ok OR error, both go back

    # 3. Settle. If the answer is a Two-Shape 'terminal screen', emit it as an artifact.
    if isArtifact(assistantMsg):
        emit({ type:"artifact", turnId, artifactId, kind, body: assistantMsg })
    emit({ type:"turn_end", turnId })

    session.thread = messages                          # persist for the next turn

Three properties make this feel like a terminal rather than a chatbot:

• Parallel fan-out. When a screen needs price plus sentiment plus insider plus analyst, the model requests all four tools in one step and the host runs them with allSettled. Never serialize independent calls. This is Synthesis Rule 9 made concrete.
• Errors go back into the loop, not to the user. A failed handler returns a structured error result the model can reason about ("no current sentiment reading for $X") instead of throwing. This is what lets the agent silently degrade (Authoring Style: no apologies) instead of dead-ending.
• The loop terminates on a text-only step. The model signals "done" by producing a turn with no tool calls. Cap the iterations (a small bound, e.g. 6) so a misbehaving plan cannot spin.

The tool registry

A tool is four parts. The model sees the first three; the host keeps the fourth private.

{
  name:        "get_quote",                 # stable identifier, shown in chips
  description: "Live price + day change for one ticker.",
  input:       { ticker: "string, e.g. NVDA" },   # JSON Schema the model fills in
  handler:     async ({ticker}) => callApi(...)     # host-only; injects the key
}

The registry is the single source of truth for what the model can do. It maps one-to-one onto the cost-ordered tool ladder in Grounding the agent (tool ladder); build exactly these and nothing the model can call that you have not wrapped:

| Tool | Ladder rung | Wraps (endpoint) | |------|-------------|----------------------------------------| | read_screen({ target }) | 1 (free) | nothing; reads the local snapshot cache | | get_quote(ticker) | 2 (live) | GET /api/v1/stocks/price?ticker={T} | | get_chart_summary(ticker, timeframe) | 2 (live) | GET /api/v1/stocks/chart?ticker={T}&timeframe=1M | | get_metrics(ticker) | 2 (live) | GET /api/v2/metrics/entity/{T}/metric/sentiment | | get_ai_summary(ticker, depth) | 3 (pre-computed) | GET /api/v1/stocks/{T}/ai-summary?depth=basic\|deep | | get_insights(ticker) | 3 (pre-computed) | GET /api/v1/insights/stock/{T} | | search_documents(query) | 4 (topical) | GET /api/v1/documents/search |

Handler rules, non-negotiable:

• The handler injects X-SentiSense-API-Key, not the model. The key lives in host process state (SENTISENSE_API_KEY), is read inside the handler, and never enters the message history, a tool argument, or an emitted event. A model that cannot see the key cannot leak it.
• The handler normalizes the response before returning it. Do the wrap-vs-flat unwrapping, the metricValue.value.value extraction, and the epoch-seconds-vs-ms fixes (see API shape gotchas) inside the handler so the model reasons over clean values, not raw envelopes.
• Every handler must hit the API (or the read_screen cache), never training memory. This is what keeps extensibility from reintroducing the stale-number failure the ladder exists to prevent.
• The registry filters by surface. exposedFor(surface) returns only the tools that make sense where the user is: a ticker dashboard exposes read_screen('dashboard'); a cold omnibox thread with no active ticker does not. Narrowing the toolset per surface is how you stop the model from calling read_screen when there is no screen.

The host-to-model contract

Each turn, the host injects three things and the model returns two. Nothing else crosses the boundary.

HOST INJECTS                         MODEL RETURNS
-----------------------------        ----------------------------
1. surface preamble  (context)       a. text deltas   (the reply)
2. exposed tool schemas (registry)   b. tool calls    (name + args)
3. thread history    (memory)

The surface preamble is a short bracketed line the host prepends to the user message at runtime (detailed in Building a multi-surface terminal). It tells the model where the user is, what is already on screen, and the preferred response shape:

[Surface: ticker-dashboard. Active ticker: $NVDA. Visible widgets: price chart,
metrics, news, peers. Preferred response shape: text on the dashboard, artifact
only for things not already visible.]

This preamble is host-emitted runtime context, not skill-authored content, and it is what lets the model resolve "it" / "this company" to the active ticker and pick a shape instead of guessing. One hard boundary: this skill is one input to your host prompt, never a replacement for it. Grounding requirements ("call read_screen('dashboard') before quoting a number") live in your host system prompt; the skill describes the pattern but cannot enforce it.

Session and context state (what persists vs resets)

The terminal feels alive because the thread has memory, and it feels haunted when the wrong state carries across a context change. Be deliberate about scope:

| State | Scope | Lifecycle | |-------|-------|-----------| | Thread messages | Per thread | Persist across turns; this is the conversation | | tickerContext (active symbol) | Per thread | Persist until the user changes ticker | | read_screen snapshot cache | Per surface | Reset on context change; see The trust layer | | Current-artifact + source-mix-expansion selection | Per surface | Reset on context change (State hygiene) | | institutional/quarters -> latestQuarter | Per session | Cache for the session; rarely changes (Synthesis Rule 10) | | Resolved headline titles | Per session | Cache 30 min keyed by URL (Headline Resolution) | | SENTISENSE_API_KEY | Host process only | Never enters thread, model context, or events |

The rule of thumb: continuity of the chat thread is a feature; continuity of UI selection across contexts is a bug. When the active ticker changes, keep the thread, drop the snapshot cache and the selection state, and let the new context start clean. The write-through snapshot cache that read_screen reads (ru

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SentiSenseApp
• Source: SentiSenseApp/skills
• License: MIT

Install and usage instructions live in the source repository linked above.