SDK & API reference

Reference

Every file, field, interface and limit, in one place. For the story of how these fit together, read the developer guide.

Versions

An older app shows an item that uses a part or grant it doesn't know as needs a newer app, and never installs half of it.

Repository and market.toml

market.toml
items/<id>/
  item.toml
  text/{en,zh-Hans,zh-Hant,ja,ko}.toml
  logo.png | logo.svg                     (optional)
  skills/<name>/SKILL.md [+ files]       (skillPack)
  tool/{Cargo.toml, Cargo.lock, src/, wit/, server.wasm}   (sandboxedServer)
  agent/agent.toml, agent/skills/<name>/   (agent)
  plugin.toml                              (agent)
  page/{package.json, package-lock.json, src/, …}   (page; dist/ is built)

market.toml

publisher = "Tallgeese"          # default publisher where an item.toml has none

[[categories]]                   # categories beyond the app's own
id = "travel"
text = { en = "Plan a trip", zh-Hans = "规划旅行", zh-Hant = "規劃旅行", ja = "旅行を計画する", ko = "여행 계획하기" }

Item ids document-reader and web-search are the app's own and are reserved: a catalog can't restate them or use them as ids.

item.toml

Top-level fields

icon

offer

[offer]
kind = "free"

[offer]
kind = "paid"
price = "US$4.99"              # shown on the page; at most 24 characters
amount = 499                   # charged, in the currency's smallest unit; more than 0
currency = "usd"               # three lowercase letters
tax_code = "txcd_10202000"     # optional, one of Stripe's

A paid item must bring skills (a skillPack): what is paid for is the download. The checkout charges the amount and currency from the signed catalog and nowhere else.

Part: skillPack

[[provides]]
kind = "skillPack"
skills = ["meeting-minutes", "follow-up-email"]

At most one skillPack per item. All of the item's skills go in it. A pack is at most 1 MB. Delivered as <item>-<version>.tgspack.

Part: remoteServer

[[provides]]
kind = "remoteServer"
server = "sample-wiki"
url = "https://wiki.example/mcp"
auth = "oauth"
tools = { only = ["search", "read_page", "write_page"], ask = ["write_page"] }

Requires network = "online". One server (remote or sandboxed) per item. Nothing is downloaded: the item holds only the address.

How sign-in works

The first time the person presses Sign in, the app registers itself with the service (RFC 7591, dynamic client registration) under the name Tallgeese, then hands the result to the agent, which completes the browser sign-in. Services that don't accept unknown apps, or that require a client secret, can't be used yet.

Part: sandboxedServer

[[provides]]
kind = "sandboxedServer"
server = "finance"
grants = ["storage"]
allow = { http = ["https://query1.finance.yahoo.com:443", "https://www.sec.gov:443"] }
tools = { ask = ["record_trade"] }

Needs tool/ with the source and the built server.wasm (at most 4 MB). An https origin requires network = "online". Delivered as <item>-<version>.tgstool.

Part: runtime

[[provides]]
kind = "runtime"
family = "python"

family is one of the app's own add-ons: today "python". The catalog names a family and never an address or hash; the app downloads its own pinned, hash-checked build the first time an item that asks for one is got, and removes it with the last item that uses it. An item with a runtime must also bring a skillPack or a server that uses it. At most one.

Part: agent

[[provides]]
kind = "agent"
role = "tg_financial_advisor"
area = "their investments, portfolio or watch list, or prices or news about a stock or fund"

Needs a sandboxedServer, agent/agent.toml, and (if it has any) agent/skills/. At most one. Delivered in <item>-<version>.tgsplugin with the page.

Part: page

[[provides]]
kind = "page"
id = "financial-advisor"
glyph = "chart"
calls = ["list_portfolio", "asset_mix", "delete_account"]
confirms = ["delete_account"]
actions = ["trade", "review"]

Needs an agent. At most one page. The page's files are in the same .tgsplugin as the agent.

text/<locale>.toml

name = "Financial Advisor"
tagline = "Follow your investments, with prices and news"
description = "A watch list of the stocks and funds you follow…"
tasks = ["Keep an eye on stocks and funds", "See how my investments are doing"]
prompts = ["Watch Tesla and Amazon for me", "How did my investments do this month?"]

[plugin]     # specialists: labels for settings, groups and permissions
"settings.price_service" = "Price service"
"settings.price_service.tiingo" = "Tiingo (US stocks and funds)"
"groups.prices" = "Get prices instantly with your own free key"
"permissions.trades" = "Record a trade"

[page]       # specialists: action buttons, and the page's own words
"actions.trade" = "I'd like to record a trade I made"
"advisor.disclaimer" = "It isn't professional financial advice."

SKILL.md

---
name: meeting-minutes
description: "Write meeting minutes from rough notes. Use when someone gives notes or a transcript of a meeting and wants minutes, action items, or a follow-up."
---

# Writing minutes
…

How the assistant reaches your skill

Tallgeese gives the assistant two read-only abilities for skills:

Tool interface (WIT)

A sandboxed tool is a WebAssembly component built for wasm32-wasip2 that exports one small interface. The app serves it to the agent as an MCP server over stdio, run from the app's own program.

Version 0.1.0

package tallgeese:tool@0.1.0;

interface tools {
  /// Its tools, as a JSON array of MCP tool descriptions:
  /// [{ "name", "description", "inputSchema" }, ...]. The same every time.
  describe: func() -> string;

  /// Runs the tool `name`. `arguments` is the JSON object the agent sent.
  /// ok: the answer, as text for the agent; err: the same, as an error.
  call: func(name: string, arguments: string) -> result<string, string>;
}

world tool { export tools; }

Gets HTTP (through wasi:http) to the origins in allow.http, and nothing else.

Version 0.2.0

package tallgeese:tool@0.2.0;

interface types {
  variant value { null, integer(s64), real(f64), text(string), blob(list<u8>) }
  type row = list<value>;
  record statement { sql: string, params: list<value> }

  /// `text` for the agent; `structured`, JSON, for the item's page only.
  record answer { text: string, structured: option<string> }
}

/// Only for a tool whose manifest has the `storage` grant: any other that
/// imports it doesn't start. `params` are bound in order.
interface storage {
  use types.{value, row, statement};
  query:   func(sql: string, params: list<value>) -> result<list<row>, string>;
  execute: func(sql: string, params: list<value>) -> result<u64, string>;
  batch:   func(statements: list<statement>) -> result<_, string>;
}

/// The person's settings for the item, by id; a secret only to the tool.
interface config { get: func(id: string) -> option<string>; }

interface clock {
  /// The date (YYYY-MM-DD) at `ms` since 1970 UTC, where the person is.
  local-date: func(ms: s64) -> string;
}

interface tools {
  use types.{answer};
  describe: func() -> string;
  call: func(name: string, arguments: string) -> result<answer, answer>;
}

world tool {
  import storage;
  import config;
  import clock;
  export tools;
}

Sandbox and budget

Every call gets a fresh instance with WASI granted nothing, HTTP through a gate, and these limits:

HTTP is checked against the manifest's allow.http origin by origin, and the origin of each request is the same form as in the allow list (scheme://host:port, lowercase, port written out). A request to anything else fails.

When tools.only is set, only those tools are offered to the agent; the others are hidden even though the component describes them.

Storage

One SQLite file per item at app/plugins/<item>/data.sqlite, in WAL mode with a 5-second busy timeout. The agent's server and the page each hold a connection of their own; one can write while the other reads.

Project and build

[package]
name = "zotero-tool"
version = "1.0.0"
edition = "2021"
license = "MIT"
publish = false

[lib]
crate-type = ["cdylib"]

[dependencies]
wit-bindgen = "0.63"
wstd = "0.6"          # async HTTP and timers on wasi:http
serde_json = "1"

[profile.release]
opt-level = "s"
lto = true
codegen-units = 1
strip = true
panic = "abort"

# Built on its own, for WebAssembly.
[workspace]

wit_bindgen::generate!({ path: "wit", world: "tool" });

use exports::tallgeese::tool::tools::{Answer, Guest};
use tallgeese::tool::types::Value;
use tallgeese::tool::{clock, config, storage};

struct Tool;
impl Guest for Tool {
    fn describe() -> String { /* JSON array of tools */ String::new() }
    fn call(name: String, arguments: String) -> Result<Answer, Answer> {
        let key = config::get("price_key");                          // Option<String>
        let today = clock::local_date(1_700_000_000_000);             // "YYYY-MM-DD"
        let rows = storage::query("SELECT n FROM t WHERE id = ?1", &[Value::Integer(1)]);
        Ok(Answer { text: "…".into(), structured: Some("{\"n\":1}".into()) })
    }
}
export!(Tool);

Put the matching tool.wit (0.1.0 or 0.2.0, both shown above) in tool/wit/. The builder uses a fixed Rust toolchain supplied with the Developer Kit:

rustup target add wasm32-wasip2
tgs-market build-tool items/<id>       # cargo build --release --locked --target wasm32-wasip2

The build records no paths from your computer, so the same source gives the same file everywhere. tgs-market check-tools builds again and fails if the result differs from the server.wasm you saved.

The tool's signed manifest tool.json

You don't write it: the release does. For reference, it is a signed envelope holding one object under tool:

{ "tool": {
    "schema": 1, "item": "zotero", "version": "1", "server": "zotero",
    "component": { "path": "server.wasm", "size": 123456, "digest": "sha256:…" },
    "allow": { "http": ["http://127.0.0.1:23119"] },
    "tools": { "only": [], "ask": ["add_reference"] },
    "grants": ["storage"]            // omitted when none
} }

The app verifies the signature, the item and version, and the component's size and digest every time the tool starts, and refuses a tool whose manifest isn't the one the person approved (a fingerprint of the signed payload).

agent/agent.toml

name = "tg_financial_advisor"
description = "The person's investments: …"
model_reasoning_effort = "medium"
nickname_candidates = ["Advisor"]
developer_instructions = """
You are the Financial Advisor, a specialist inside Tallgeese. …
"""

Nothing else is allowed. Keys that would change tools, the sandbox, approvals or the assistant (such as mcp_servers, sandbox_mode, approval_policy or model) are refused: the app controls those.

What the app adds to the specialist's instructions

1. Your developer_instructions.
2. "The person's settings": for example the currency, and whether a price service is set. Never a secret.
3. "Your skills": each of agent/skills/* by name, description and file, to read when one applies.

The app assembles them each time it starts a specialist thread, so a changed setting applies to the next one. The thread has your tool switched on; the main conversation's never does. agent/ holds agent.toml and skills/ and nothing else. Skills in agent/skills/ follow the same rules and may not share a name with the item's pack skills.

The main chat's ask_<role> tool

The app adds one tool per enabled specialist to every main conversation (and every scheduled run). Its description is your area, with "it holds the person's data and the tools for it; you don't", and instructs the assistant to pass the request as the person put it and relay the answer with its caveats. When called, the app runs a turn on the specialist's thread and answers with its last message. A failed turn answers as an error that says why. The exchange shows in the main chat as an "Asked <name>" card.

plugin.toml

Settings the person can change, permissions they can set, and what the tool keeps. Only for items with an agent.

[[settings]]

[[settings]]
id = "home_market"
kind = "choice"
choices = ["auto", "US", "UK", "JP"]
default = "auto"
group = "market"

[[settings]]
id = "price_key"
kind = "secret"
group = "prices"
links = { tiingo = "https://www.tiingo.com/account/api/token" }

[[permissions]]

[[permissions]]
id = "trades"
default = "ask"          # or "allow"
tools = ["record_trade"]

A permission the person can switch between "ask first" and "allow". tools are tools the item's tool really offers; a tool is in at most one permission. A permission's id is lowercase letters, digits, _; up to 32; unique.

[data]

[data]
storage = true            # must go with grants = ["storage"] in item.toml
export = ["json", "csv"]  # the formats "Export my data" offers

Text keys the checker expects

For each setting, "settings.<id>"; for each choice, "settings.<id>.<choice>"; for each group, "groups.<group>"; for each permission, "permissions.<id>" — all under [plugin] in every language's text/*.toml.

Page API (host)

A page is a web page that runs in a sandboxed frame: sandbox="allow-scripts", no origin of its own, no network. The frame is served as tgsplugin://localhost/<item>/<version>/index.html (http://tgsplugin.localhost/… on Windows). The app hands the page one MessagePort when it loads, and answers only on that port. @tallgeese/plugin-page wraps it as host.

import { host } from "@tallgeese/plugin-page";

const told = await host.init();   // call this first; anything before it is refused

Content Security Policy

default-src 'none';
script-src 'unsafe-inline' tgsplugin: http://tgsplugin.localhost;
style-src  'unsafe-inline' tgsplugin: http://tgsplugin.localhost;
img-src    data: tgsplugin: http://tgsplugin.localhost;
font-src   data: tgsplugin: http://tgsplugin.localhost;
base-uri 'none'; form-action 'none'

There is no connect-src: a page can't fetch. Inline script is allowed because a page is usually one file (Vite's single-file build). The package serves only files its signed manifest lists, and checks each one's digest as it serves it.

Methods

Init

interface Init {
  apiVersion: number;                 // 1
  item: string;
  version: string;
  locale: string;                     // the person's language
  strings: Record<string, string>;   // your [page] text in that language (or English)
  theme: { mode: "light" | "dark"; tokens: Record<string, string> };
  settings: Record<string, unknown>;  // what the page may see; a secret only as true/false
  calls: string[];                    // tools the page may call
  confirms: string[];                 // of those, ask the person yourself first
  kept: Record<string, string>;      // what host.keep stored
}

Events

Theme tokens

theme.tokens maps names, without the leading --, to values (primary, surface, …). Apply them as CSS custom properties so the page looks like the app:

for (const [name, value] of Object.entries(theme.tokens))
  document.documentElement.style.setProperty(`--${name}`, value);
document.documentElement.dataset.theme = theme.mode;

Log the tokens once in your page's development build to see which names the app currently provides.

Rules and limits

What a page never gets: the conversation, approvals, secrets, the person's files, other items' tools, or the network. A frame that loads a second time has navigated away and gets no port.

Recommended build: Vite with base: "./" and a single-file output. React works (about 45 KB gzipped); Preact is smaller. tgs-market build-page items/<id> builds it using the lock file you saved; review builds it twice and fails if the two results differ.

Built-in tools you can rely on

These ship in the app, are always available to the agent, and need no item. Your skills may name them.

Web: search and fetch

Documents: document_info, read_document, read_sheet, render_pdf_page

Formats: PDF, Word (.docx, .doc), PowerPoint (.pptx, .ppt), spreadsheets (.xlsx, .xls, .ods, .csv, .tsv), OpenDocument (.odt, .odp), Hangul (.hwp, .hwpx), RTF, EPUB, and text or Markdown in any encoding.

Skills: load_skill, read_skill_file

Described above.

Catalog and packages

You don't write these, but you may want to inspect them. A release is a folder:

catalog.json                                   signed
packs/<item>-<version>.tgspack                the skills
tools/<item>-<version>.tgstool                 tool.json (signed manifest) + server.wasm
plugins/<item>-<version>.tgsplugin             plugin.json (signed manifest) + agent.toml + plugin.toml + text.json + skills/ + page/

Signed envelopes

Every document in a release is signed, and each kind is wrapped so it can't be mistaken for another.

Catalog shape

{
  "schema": 1,
  "version": 17,                        // release number; only goes up
  "categories": [{ "id": "finance", "text": { "en": "…", "ja": "…" } }],
  "items": [{
    "id": "financial-advisor", "version": "2", "publisher": "Tallgeese",
    "categories": ["finance"],
    "icon": { "glyph": "chart", "tint": "sage" },
    "offer": { "kind": "free" },
    "network": "online",
    "platforms": [],                     // omitted when for all
    "provides": [
      { "kind": "sandboxedServer", "server": "finance",
        "package": { "url": "/v1/tools/financial-advisor/2", "size": 0, "sha256": "…" },
        "allow": { "http": ["https://www.sec.gov:443"], "storage": true },
        "tools": { "ask": ["record_trade"] } },
      { "kind": "skillPack", "package": { "url": "/v1/packs/…", "size": 0, "sha256": "…" }, "skills": ["…"] },
      { "kind": "agent", "role": "tg_financial_advisor", "area": "…", "package": { "url": "/v1/plugins/…", "size": 0, "sha256": "…" } },
      { "kind": "page", "id": "financial-advisor", "glyph": "chart", "calls": ["…"], "confirms": ["…"], "actions": ["…"] }
    ],
    "text": { "en": { "name": "…", "tagline": "…", "description": "…", "tasks": ["…"], "prompts": ["…"] } }
  }]
}

Note that in the catalog the storage grant is allow.storage = true, while in item.toml it is grants = ["storage"]. The release converts one to the other. The app reads at most 4 MB of catalog, envelope and all.

What the app checks, and when

1. On getting: the catalog's signature; each package's size and SHA-256 against the catalog; then the signed manifest is this item's; then the files are exactly the manifest's.
2. On using: the tool at each start (signature, fingerprint approved by the person, component digest); each page file as it is served.
3. On a new version: the person is asked again if what the item reaches, keeps or adds changed.

tgs-market command line

Environment for dev

The dev daemon reads them when it starts: TGS_ADDONS_URL=… TGS_ADDONS_KEYS=… npm run dev.

All limits in one table

Checker messages and what to do

The checker prints every problem, each starting with where it is. Some you will meet first: