UniloomDocs
Use Uniloom

Widget API

This is what a widget can import from Uniloom. Your agent gets the same API as TypeScript declarations from get_widget, and Uniloom type-checks every save against them, so a wrong call is an error at its file and line before the widget runs.

Contents#

The tools and the files#

An agent builds a widget with two MCP tools, both taking widget_id:

  • get_widget returns the files, the playbook (the rules for building a widget), sdk (the whole API as declarations), examples (4 whole widgets: a sessions chart, a tasks list that adds a task, notes kept with useStore, a doc written from commits) and the workspace's other widgets by id and title.
  • publish_widget sends the files and returns render (below).

A widget is index.html with one <script type="module" src="./App.tsx"></script>, plus files ending in .tsx .ts .jsx .js .css .json .md .svg, in any folders, at most 300. It may import its own files and react, react-dom/client, lucide-react, @uniloom/sdk, @uniloom/sdk/react, @uniloom/sdk/format and @uniloom/ui.

uniloom.json says what it is and what it asks for:

{
  "name": "Reviews",
  "place": "home",
  "sdk": 1,
  "permissions": [{ "use": "tasks.write", "why": "Move a review to tomorrow" }],
  "tools": [{ "tool": "linear__list_issues", "why": "Show my open issues" }]
}
  • place is "home", "activity" or "sessions": the tab it shows on.
  • sdk is the API version it was made for, now 1. Within a version Uniloom only adds calls and parts.
  • Every call that needs a permission must have it listed, and every listed permission must be used by a call. Either mistake is a build error at its line.

Permissions and errors#

PermissionOn screen
workspace.readRead your workspace
tasks.readRead your Tasks
tasks.writeChange your Tasks
github.readRead your GitHub
github.actAct on your GitHub
memories.writeSave memories
docs.writeWrite docs
routines.runRun automations
sessions.startOpen AI sessions

A refused call throws UniloomError with a code:

CodeMeans
not_alloweduniloom.json does not list the permission, or the call needs the person's OK where no card can show
not_grantedListed, but the person has not allowed it yet, or an MCP tool changed
bad_requestThe arguments are wrong, or the target is not one the widget may touch
failedUniloom could not do it
no_answerNo answer came
too_oftenPast a rate limit (toasts, GitHub actions)
declinedThe person pressed Not now on the card
busyAnother card is waiting for the person's answer

A call that needs the person's OK each time (memories.save, docs.create, docs.append, routines.run, sessions.start and every github.* action) shows Uniloom's card above the widget, on its tab and in the Widgets preview, and waits for the answer. It runs only on the person's yes. Where no card can show (a thumbnail, the render check), it is refused with not_allowed. A call needing a permission not yet allowed is refused with not_granted. Each message says what to do, so show it.

Reading#

Every read stays inside the widget's workspace. since is "1d", "7d", "30d" or "90d". Lists come newest first, at most limit rows (default and maximum 5,000); pass the last row's time as before to read on.

CallReturnsNeeds
uniloom.place.get()What the widget's tab shows now (below)—
uniloom.project.get()Where the widget was made: a project, or the workspace (kind)workspace.read
uniloom.docs.list({ limit })The workspace's docs, each with its kindworkspace.read
uniloom.docs.get(id)One doc with its textworkspace.read
uniloom.memories.list({ limit })The workspace's memories, without those kept away from widgetsworkspace.read
uniloom.memories.search(text)The best matches, ranked like recallworkspace.read
uniloom.sessions.list({ since, limit })AI sessions: tool, date, title, summaryworkspace.read
uniloom.sessions.count({ days })Sessions per day (default 7, at most 90) and per toolworkspace.read
uniloom.sessions.live()Sessions running now; status is working, needs_you or idleworkspace.read
uniloom.usage.list({ since, limit })Tool, model, time, prompts, tokens and cost per session (default 30 days)workspace.read
uniloom.receipts.list({ since, limit })Sessions that ran a check, changed a file or made a commit (default 7 days)workspace.read
uniloom.activity.list({ since, kinds, limit })Git activity (default 7 days); kind is commit, branch.created, branch.switched, branch.deleted, staged or files.touchedworkspace.read
uniloom.artifacts.list({ limit })The workspace's artifacts, each with a linkworkspace.read
uniloom.routines.list()The workspace's automationsworkspace.read
uniloom.tasks.list({ section, open })Items in Tasks; open defaults to truetasks.read

The tab it reads#

uniloom.place.get() takes no arguments; Uniloom fills in what the tab shows. Read again on uniloom.on("place").

  • activity: { place, from, to, days, project, sessions, memories }. The sessions that started in the range and project picked in Activity, and the memories learned in the range (not narrowed to the project).
  • home: { place, project, running, tasks, finished }. Sessions running now, your open tasks, and receipts of sessions that finished in the last day. tasks is empty unless the widget lists tasks.read and the person allowed it.
  • sessions: { place, session }. The session open beside it, or null. session holds tool, title, branch, status, lastActiveAt, project, githubRepo ("owner/name" or null), and from the last week's usage model, startedAt, activeMs, prompts, tokens and costUsd, each null when not measured. To show the issues of the session's project, read uniloom.sources.tasks({}) and keep rows whose key starts with githubRepo and #, ignoring case.

Lists from outside Uniloom#

A widget has no network. Uniloom reads outside lists itself, keeps the rows, and answers at once with { rows, fetchedAt, status, detail }. status is "ok", "stale" (Uniloom is reading again) or "failed" (rows are the last good ones). Hidden characters are removed from the rows. Read a source with useSource and show SourceStatus beside it.

CallReturnsNeeds
uniloom.sources.tasks({ section, open })Items in Tasks, with when they last synced. section is solve, review, reply or todotasks.read
uniloom.sources.reviews()Open pull requests waiting for your review, at most 50github.read
uniloom.sources.pulls()Your own open pull requestsgithub.read
uniloom.sources.repoPulls()Open pull requests in the workspace's projects, anyone's, at most 50. Uniloom picks the projectsgithub.read
uniloom.sources.checks({ repo, number })The checks on one pull request from reviews or pulls; any other is bad_requestgithub.read

GitHub is read with the workspace's gh sign-in. Uniloom keeps rows for 2 minutes, does not ask again within 20 seconds, and starts at most 12 GitHub reads a minute across all widgets; past that a read answers "failed" with the last rows.

Your MCP tools#

CallReturns
uniloom.tools.list()The tools this widget may read through now: name, server, description, input schema
uniloom.tools.read({ tool, args })One tool's answer as a source: rows holds one { text, truncated }

List each tool under tools in uniloom.json as <server>__<tool>, at most 20. The person allows each one, as read-only, with its switch in Widgets. A tool whose name says it writes (create, update, send…), or whose server marks it readOnlyHint: false or destructiveHint: true, is refused with not_allowed. If the tool's name, description, input schema or hints change, calls are refused with not_granted until the person allows it again.

args must match the tool's input schema and be at most 4,000 characters as JSON, or the call is bad_request. The answer is cut at 20,000 characters (truncated: true). Uniloom keeps an answer for 1 minute, does not repeat a call within 10 seconds, and allows each server 20 requests a minute from all widgets.

Acting#

CallDoesNeeds
uniloom.tasks.create({ title, remindAt })Adds an item of your own; title at most 200 characterstasks.write
uniloom.tasks.remind(id, when)"tomorrow", "next-week" (both 9:00) or an ISO time, for an item this widget madetasks.write
uniloom.tasks.done(id)Marks an item this widget made as donetasks.write
uniloom.memories.save({ text, kind })Saves a new memory, held until the person releases itmemories.write
uniloom.docs.create({ title, text })A new doc in the widget's project (markdown)docs.write
uniloom.docs.append(id, text)Adds markdown to a doc in the widget's projectdocs.write
uniloom.routines.run(id)Runs an automationroutines.run
uniloom.sessions.start({ prompt })Opens a session with the prompt typed insessions.start
uniloom.github.approve({ repo, number })Approves a pull request waiting for your reviewgithub.act
uniloom.github.changes({ repo, number })Requests changes on onegithub.act
uniloom.github.comment({ repo, number })Comments on one from either listgithub.act
uniloom.github.label({ repo, number, label, remove })Adds an existing label, or removes onegithub.act
uniloom.ui.open(link)Opens uniloom://doc?id=…, uniloom://task?id=… or uniloom://artifact?id=…workspace.read
uniloom.ui.toast(text)A short note, at most one a second, 200 characters—

The calls that need the person's OK wait for their card (above). sessions.start opens on the project the tab shows and fails without one. A GitHub action is limited to 5 an hour per widget and 20 for all widgets, and the words are always the person's, never the widget's. Text a widget writes is bad_request if it holds invisible characters such as zero-width or direction-changing ones.

Its own data and events#

uniloom.store.get(key), set(key, value), delete(key) and keys() keep the widget's data on this computer, never synced, at most 1 MB in all.

uniloom.on(area, fn) calls fn when data changes in "docs", "memories", "tasks", "sessions" or "activity", or "changed" for any change. "place" fires when the tab shows another range, project or session. It returns a function that stops listening.

@uniloom/sdk/react#

HookDoes
useQuery(load, deps, { on }){ data, loading, error, refresh }, keeping the last answer while it reads again. Rereads on docs, memories and tasks by default; on replaces that list
useSource(load, deps, { on })For uniloom.sources.* and uniloom.tools.read: { rows, fetchedAt, status, detail, loading, error, refresh }. While "stale" it asks again every 1.5 seconds, up to 8 times
useStore(key, initial)[value, setValue] for one value of its own data

@uniloom/sdk/format#

dayOf(at) and lastDays(n) give "YYYY-MM-DD" days, the keys sessions.count uses. dayLabel(day) gives "Mon 12". duration(ms) gives "45s", "12m", "3h 20m". compact(n) gives "940", "12.4k", "1.2M". money(usd) gives "$3.10" or "<$0.01". count(n, "session") gives "1 session" or "3 sessions". timeZone() gives the person's time zone.

@uniloom/ui#

The card#

The root is always <Widget>. It takes the look of the tab it sits on, so a widget never styles its own card. Lay it out with these; each takes hideBelow="medium" or "wide":

  • Widget: the root; gap is 1 to 4.
  • Stack: parts one under another (grow, gap, align, justify). Inline: side by side (wrap).
  • Panel: a quiet section. Divider: a line (vertical in an Inline).
  • Fit: the focal element, scaled to the room left. Give its child a size (<svg width={120} height={120} viewBox="0 0 100 100">).
  • Metric (size md, lg, xl), Label and Caption: all text.
  • useCard(): the card's width, height and size ("small" under 260 px, "wide" from 420 px, else "medium").

Colours#

color holds the theme's colours: text, muted, surface, bg, border, hover, accent, accentText, ok, attention, bad, and chart (5 colours). As CSS: var(--text) … var(--bad), var(--accent-text), and var(--c1) to var(--c5). They follow light and dark.

Parts#

  • Rows: Card, Row, Header, SectionLabel
  • A read's state: QueryView (for useQuery: waiting, error with Retry, empty, or your view) and SourceStatus (for useSource)
  • Charts: BarList, Sparkline, StatCard, RankedList
  • Controls: Button, IconButton, Input, Textarea, Select, Checkbox, Switch, Segmented
  • Display: Badge, Chip, Avatar, Kbd, When
  • States: Callout, EmptyState, ErrorState, Loading, Spinner, Skeleton, SkeletonLines

The checks each version passes#

The build refuses, at its file and line: a colour, text size or font written by hand (hex, rgb(), a colour name, a raw palette step like var(--n-500)), a size read from the window (vh, vw, h-screen, window.innerWidth), position: fixed, Page, Section or Grid, and a root that is not <Widget>.

The render check then runs the version once, hidden, with no network. Writes and outside reads get no answer. It fails when the widget throws, when a call is refused with not_allowed, bad_request or failed, or when nothing shows within 10 seconds. not_granted does not fail it. A widget that drew is run again in 3 boxes at its height (480 px while its height follows it): its own width, the narrowest its tab allows, and the whole row. It fails as clipped if its content is taller or wider than a box, or cut off inside it. So lay it out with Stack and Inline, and put the focal element in Fit.

render.status is ok, failed or pending (no window has run it yet; call get_widget later). On failed, each of problems has kind (threw, refused, blank or clipped), call, code, errorClass, file and line, and for clipped a fit with span, width, height, what (height, width or inside), measured and allowed in px. next says the fix in one line.

import { createRoot } from "react-dom/client";
import { uniloom } from "@uniloom/sdk";
import { useQuery } from "@uniloom/sdk/react";
import { BarList, Label, QueryView, Widget } from "@uniloom/ui";

function Week() {
  const week = useQuery(() => uniloom.sessions.count({ days: 7 }));
  return (
    <Widget>
      <Label>AI sessions this week</Label>
      <QueryView query={week} isEmpty={(d) => d.total === 0} empty="No AI sessions this week.">
        {(d) => <BarList rows={d.byDay.map((x) => ({ label: x.day, value: x.count }))} />}
      </QueryView>
    </Widget>
  );
}

createRoot(document.getElementById("root")!).render(<Week />);

This example needs workspace.read in uniloom.json.

Last updated