SDK reference

The Egg SDK is a TypeScript package, @egg/sdk, for building Egglets. An Egglet is a portable app that talks to the Egg Gateway over loopback HTTP and runs anywhere a modern browser can render it: the Egg desktop app, Chrome, Safari, or any other current browser. Authors install the SDK, export an activate(ctx) function, and receive an EggletContext with every host capability the Egglet’s manifest permits: database, AI (text, image, audio, video), scheduled work, cross-Egglet messaging, refs, credentials, file URLs, the user’s tier, and more.

This page is the field-by-field reference for EggletContext. Sections are grouped into tiers — Primitives (the universal toolkit), Capabilities (model / media / extension access), Runtime services, Egg domains, and the escape hatch. Each method card shows what it does, its parameters, its return shape, the errors it can raise, and the manifest declaration required to call it when one is needed. Calling the Egg Gateway from outside an Egglet (a Chrome extension, an agent skill, the CLI) takes a different path; see the HTTP API reference for that.

import { defineEgglet, type EggletContext } from "@egg/sdk";

export default defineEgglet({
  activate(ctx: EggletContext) {
    // ctx.ai, ctx.database, ctx.log, ...
  },
});

EggletContext.log

Tagged logger scoped to the Egglet’s id. Calls forward to the host console with a [egglet:<id>] prefix. No manifest declaration required. Use this instead of bare console.log so output is attributable.

EggletContext.routes

Mount the Egglet’s top-level view at the path declared in manifest.route. The Egglet does not pick the path; the manifest does. The host calls the loader on first activation of the route and keeps the component mounted thereafter (the view participates in the keep-alive panel system; switching tabs does not unmount it). Two Egglets cannot mount the same route.

ctx.routes.mount(() => import("./MyEggletPage"));

EggletContext.tools

Register named tools the agent and other Egglets can call. Tool names are namespaced by convention: <egglet_id>.<verb>. Every name passed to register must appear in manifest.tools. Cross-Egglet calls require both external: true on the owning manifest and a matching entry in the caller’s permissions array.

ctx.tools.register<{ id: string }, { count: number }>(
  "myEgglet.countItems",
  async ({ id }) => {
    const row = await ctx.database.one<{ n: number }>(
      "SELECT COUNT(*) AS n FROM {{items}} WHERE owner = ?",
      [id],
    );
    return { count: row?.n ?? 0 };
  },
);

EggletContext.database

Read and write the Egglet’s tables. SQL strings reference tables by their logical name wrapped in double curly braces: {{items}}. The host substitutes the placeholder with the physical name from the manifest before sending the query. SQL referencing tables not declared by the manifest is rejected. Reads run against the local connection directly; writes route through the Gateway daemon so its update hooks fire and any sync push runs. From the Egglet’s perspective the calls look identical; the platform handles routing.

const rows = await ctx.database.all<{ id: string; title: string }>(
  "SELECT id, title FROM {{items}} WHERE is_read = 0 ORDER BY ts DESC LIMIT ?",
  [50],
);

await ctx.database.exec(
  "UPDATE {{items}} SET is_read = 1 WHERE id IN (?, ?, ?)",
  ["a", "b", "c"],
);

EggletContext.schedule

Recurring work the platform drives. The Egglet supplies the handler; the platform supplies the cadence and survives a closed window when the work is daemon-driven. Requires uses.gateway.schedules: true.

const handle = ctx.schedule.poller({
  name: "refresh",
  interval: 300,
  handler: async () => { await refreshFeeds(); },
});
// later, to stop it manually:
handle.cancel();

EggletContext.fetch

In-process outbound HTTP, distinct from the Gateway-driven headless path. Routes through the platform’s shared HTTP client. Requires uses.network.fetch: true.

const r = await ctx.fetch("https://api.example.com/v1/items", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ q: "today" }),
  timeoutMs: 10_000,
});
if (r.ok) { const items = JSON.parse(r.body); }

EggletContext.headless

Hidden-browser page fetch. Useful for SPAs, login-walled feeds, anything where ctx.fetch does not produce JS-rendered content. The Gateway spawns a fresh hidden browser per call. Requires uses.gateway.headless: true.

const result = await ctx.headless.fetch("https://example.com/feed", {
  waitMs: 3_000,
  evalJs: "document.title",
  credentialSource: "example",
});
console.log(result.title, result.evalResult, result.html.length);

EggletContext.web

Client-side web access — a unified surface for fetching, rendering, reading, and searching the web. Every verb runs locally: a plain HTTP request from the user’s machine, or the hidden local browser (with the user’s own session). Nothing is proxied through a cloud service, so requests stay private, cost nothing per call, and see the web as the user’s logged-in browser does. Requires uses.gateway.web: true.

const article = await ctx.web.read("https://example.com/post");
console.log(article.title, article.text?.length);

const hits = await ctx.web.search("mozilla readability library", { limit: 5 });
for (const h of hits.results) console.log(h.title, h.url);

EggletContext.files

List, delete, and resolve URLs for files the daemon has written into its generated-media store (TTS output, generated images, captured video, etc.). The Egglet receives a path back from ctx.ai.*; pass that path to urlFor to get a URL it can embed. No manifest declaration required.

const images = await ctx.files.listGenerated("image");
for (const f of images) {
  console.log(f.name, f.sizeBytes, ctx.files.urlFor(f.path));
}

EggletContext.credentials

Read access to user-authorized credentials. Egglets cannot create or revoke credentials; the user manages them in Settings. The source must appear in manifest.credentials.

const entry = await ctx.credentials.get("github");
if (!entry) { ctx.log.warn("no GitHub credential authorized"); return; }
const { token } = JSON.parse(entry.dataJson);

EggletContext.refs

Ref kinds are the cross-Egglet handle system: stable, serializable values like @e:alice-123 that can travel through tables, agent prompts, sync payloads, and other contexts. Each kind has exactly one owning Egglet, declared in manifest.refs. The owning Egglet calls register in activate() with a function that resolves an id to a RefView. Other Egglets call resolve to render or parse to extract refs from text.

ctx.refs.register("e", async (id) => {
  const row = await ctx.database.one<{ id: string; name: string }>(
    "SELECT id, name FROM {{entities}} WHERE id = ?",
    [id],
  );
  return row ? { kind: "e", id: row.id, label: row.name, route: `/people/${row.id}` } : null;
});

EggletContext.eggletIpc

Fire-and-forget messaging between Egglets. Use this for one-way signals (“new item arrived”, “follow-up needed”); use ctx.tools.call when you need a response. Both methods require uses.eggletIpc: true. Messages are dropped silently if the target has no subscribers; senders cannot tell.

// Sender
ctx.eggletIpc.send("people", { kind: "profileVisited", id: "alice-123" });

// Receiver
const handle = ctx.eggletIpc.subscribe<{ kind: string; id: string }>((msg) => {
  console.log(`from ${msg.from}: ${msg.payload.kind}`);
});

EggletContext.tier

The user’s plan tier and per-capability availability/quota. Use this to gate AI calls in the UI and avoid showing buttons the user’s plan can’t honor. Capability strings are the same daemon-side gate names used by ctx.ai.* (text_fast, vision, imagen, veo, tts, stt, etc.).

if (await ctx.tier.isAvailable("imagen")) {
  // safe to call ctx.ai.image.generate(...)
}

EggletContext.setup

A dependency preflight. The Egglet declares what it needs in manifest.setup; ctx.setup.check() evaluates those declarations against current Gateway state and returns a report the Egglet uses to gate its core UI and degrade optional features. Call it early — typically on activate(), or let the host’s Egglet chrome render the setup banner for you.

Each requirement is satisfied by a single token (need) or any of several (anyOf), and either gates the core app (omit enables) or unlocks one named feature (enables: "feature-id"). Tokens name a Gateway dependency:

const report = await ctx.setup.check();
if (!report.core.ready) {
  // report.core.missing[i] = { key, label, satisfied, setupUrl? }
  showSetup(report.core.missing);   // setupUrl is absolute, ready to open
  return;
}
if (report.features["transcription"]?.available) enableTranscribe();

interface PreflightReport {
  core: { ready: boolean; missing: RequirementStatus[] };
  features: Record<string, { available: boolean; missing: RequirementStatus[] }>;
}
// RequirementStatus = { key, label, satisfied, setupUrl? }  // setupUrl set when unmet

EggletContext.ai

All model-backed operations live here, grouped by modality: text (chat, embeddings, reranking), image, audio, and video. Every method routes through the Gateway daemon end-to-end: capability resolution, tier gating (per-day quotas based on the user’s plan), credential lookup, and the outbound HTTP call to whichever provider serves the slot all happen there. The browser shell never sees an API key.

A blocked tier returns a structured error the Egglet can surface to the user (e.g., “daily limit reached” or “not available on your plan”). Use EggletContext.tier to check availability before calling.

EggletContext.ai.audio

Speech is organized as intent verbs over one unified slot spine. The Egglet picks the intent; the user’s speech slot (Settings → Models → Speech) picks the engine, location, and voice. There are four capabilities — batch_tts, live_tts, batch_stt, live_stt (plus realtime_voice) — each an ordered fallback chain across browser / Gateway / cloud. When a slot resolves to the browser location, the verb is honored client-side with the platform’s native speechSynthesis / SpeechRecognition; otherwise it routes through the Gateway. The Egglet never names an engine or an API key.

Prefer the verbs:

• speak(text) — batch text-to-speech (batch_tts): synthesize and play a finished utterance in the page; the handle can stop() it.
• say(text) — conversational text-to-speech (live_tts): low-latency reply, browser voice when the slot says so.
• listen() — conversational speech-to-text (live_stt): a mic session emitting partial / final / end events.
• converse() — realtime duplex (realtime_voice); throws until the realtime transport ships.

The lower-level operations remain for batch work: transcribe (batch speech-to-text; accepts an http(s) URL / daemon path or a recorded Blob/File), vad (local voice-activity-detection — speech intervals, useful for chunking long recordings), and listVoices (the provider-tagged voice catalog for a picker). tts is retained; its backend field is legacy — the slot decides location now. recognize is deprecated, kept as an alias of inline transcribe.

Caveat: transcribeStatus currently reports best-effort placeholders; a real /api/ai/transcribe-ready endpoint will replace the stub.

// Speak a finished sentence, and stop it if the user navigates away.
const handle = await ctx.ai.audio.speak("Your export is ready.");
// handle.stop(); await handle.done;

// Listen to the mic with live partials.
const session = ctx.ai.audio
  .listen()
  .on("partial", (t) => setDraft(t))
  .on("final", (t) => submit(t))
  .on("end", () => setDraft(""));
// session.stop();

// Batch transcription of a recording (Blob) or an on-disk file / URL.
const { transcript } = await ctx.ai.audio.transcribe(recordedBlob);
const voices = await ctx.ai.audio.listVoices();

EggletContext.ai.image

generate calls the configured image-generation model and writes the result to a daemon-known on-disk path. Pair with EggletContext.files to render or serve it. analyze sends the image to the configured vision-capable model with a prompt; pass imagePath for files on disk or imageBase64 for in-memory bytes.

const img = await ctx.ai.image.generate({
  prompt: "a green leaf on a white background, studio lighting",
  aspectRatio: "1:1",
});
const url = ctx.files.urlFor(img.path);

const analysis = await ctx.ai.image.analyze({
  imagePath: img.path,
  prompt: "Describe the lighting and composition.",
});

EggletContext.ai.text

Operations whose input or output is plain text against the user’s configured text-model slot. chat.complete and chat.stream require uses.llm in the manifest; the slot is picked by uses.llm.role (default agent-secondary) and uses.llm.capability (default text). chat.stream emits text deltas, tool-call deltas, usage events, and a final done event; the returned promise resolves with the same shape as complete once the stream closes.

const r = await ctx.ai.text.chat.complete({
  system: "You are a concise summarizer.",
  messages: [{ role: "user", content: "Summarize this in one line: ..." }],
  maxTokens: 64,
});

const { embedding, dims, provider } = await ctx.ai.text.embed({ text: "hello world" });

const { scored } = await ctx.ai.text.rerank({
  query: "cats",
  docs: ["a cute kitten", "the weather is sunny", "a feline pet"],
  topN: 2,
});

EggletContext.ai.video

generate calls the configured video-generation model. It needs a public HTTPS seed image URL and accepts a provider-defined duration range. The daemon polls until completion (up to ~3 minutes) and returns the provider-hosted video URL. analyze sends the video to the configured video-understanding model with a prompt; pass videoPath for files on disk or videoBase64 for in-memory bytes.

const video = await ctx.ai.video.generate({
  prompt: "the leaf gently rustles in the breeze",
  imageUrl: "https://...leaf.png",
  durationSeconds: 5,
});
const description = await ctx.ai.video.analyze({
  videoPath: "/path/to/clip.mp4",
  prompt: "Summarize the action in one sentence.",
});

EggletContext.media

ffmpeg / ffprobe operations, run by the Gateway against daemon-readable file paths. Every method that writes output returns { outputPath, durationMs }; pair outputPath with ctx.files.urlFor() to render or serve it. Long operations accept an onProgress callback (0–100). Gated by uses.gateway.media.

const { outputPath } = await ctx.media.extractClip({
  inputPath: src, outputPath: "/tmp/clip.mp4", start: "00:00:05", duration: "10",
});
const url = ctx.files.urlFor(outputPath);

• probe(inputPath) — raw ffprobe JSON for a file.
• transcode(opts), concat(opts), mux(opts), adjustSpeed(opts) — re-encode / join / combine a video and audio track / change playback speed.
• extractAudio, extractClip, extractFrame, extractSubtitles, sampleScenes — pull a piece out (audio track, a clip between timestamps, a single frame, embedded subtitles as SRT, one frame per scene change).
• silenceDetect(opts) — silent ranges; transcript(opts) — captions-first transcript for a video URL; transcribe(opts) — Whisper speech-to-text of a local file or URL.
• download(opts) — yt-dlp download from any supported URL into a directory.

EggletContext.extension

Drive the Egg Chrome Extension: capture a URL in the user’s real, logged-in browser (their session and cookies) and read back what it captured — useful for content behind a login the headless fetch can’t reach. Gated by uses.extension.

• getCommand(id) — poll a command this Egglet enqueued.
• listCaptures(opts?) — read what the extension has captured (uses.extension.captures).
• status() — whether an extension is paired; not gated, safe to call on mount to warn when it isn’t.
• connect() — ensure a capture path exists, opening the one-click connect page if needed; throws ExtensionNotPaired if the user doesn’t finish.

EggletContext.jobs

The Gateway’s generic deferred-work queue. Domain features (contemplation, media downloads, agent tasks) enqueue here and hand back a Job handle; the lifecycle — wait, subscribe, cancel, children — lives on the handle, not on each domain. The queue enforces concurrency, priority, dedupe, retries, and a token budget. Gated by uses.gateway.jobs.

const job = await ctx.jobs.enqueue("media.download", { url }, { dedupeKey: url, maxRetries: 2 });
const unsub = job.subscribe((e) => { if (e.kind === "progress") setPct(e.progress); });
const result = await job.wait();   // throws if it failed / was cancelled
unsub();

The rest of the surface: list(filter?), get(id), cancel(id), and watch(onEvent, opts?) (a live feed of created/updated jobs for an activity view; returns an unsubscribe fn). Filters accept an exact kind or a prefix ("media."), a status, a parentId, or a since timestamp.

A Job<T> handle carries a snapshot (id, kind, status, progress, headline, error, parentId, attempt, createdAt, updatedAt) and methods: wait({ timeoutMs? }) (resolves with T when done, throws on failed/cancelled), subscribe(onEvent) (status/progress/log/domain events; returns unsubscribe), result(), cancel(), and children(). status is one of queued | running | paused | done | cancelled | failed.

EggletContext.thinking

Background contemplation. contemplate() seeds a durable dialectical session (thinker → challenger → judge) and runs it as a thinking job on the queue above; its distilled findings propagate into the agent’s long-term memory by default. Gated by uses.gateway.thinking.

const session = await ctx.thinking.contemplate({
  topic: "What would make onboarding feel instant?",
  sink: "memory",   // "none" keeps findings on the session only
});
const detail = await session.wait();   // { turns, findings, ... }

• contemplate(opts) — commission a session; returns a ThinkingSession handle with wait({ timeoutMs? }) and detail(). The thinking job is observable via ctx.jobs.list({ kind: "thinking" }).
• get(sessionId) — a session’s metadata, turns, and findings.
• list(opts?) — an agent’s sessions, most recent first.
• continue(sessionId, nudge?) — resume a session with an optional new angle.
• curiosity.list(opts?) — the agent’s parked follow-up questions, the agenda the service pulls from.

EggletContext.feeds

The aggregated feed store the Gateway polls — RSS, social, and scraped sites — and its items. The Feed app is one UI over this domain; any Egglet can read and manage the same data. Egg also emits feeds: channels and the feed host publish the user’s content as open, subscribable RSS.

• Feeds: list(), preview(url) (fetch + autodiscover the feed link + parse, returning the resolved URL and sample items; throws if none is found), create(req), update(id, patch), remove(id).
• Polling: poll(id), pollAll(), pausePolling(), resumePolling().
• Items: items(opts?), itemsFor(feedId, opts?), unreadCount(), markRead(ids), flag(ids, flagged).
• scrape(url, opts?) — a one-off extractor run; digest() — the daily summary of new and top-scoring items across all feeds.
• Channels (feeds.channels): list(), create(req), update(id, req), remove(id) — saved-filter feeds carved out of the item store (by platform, relationship, or keyword), each served as its own RSS. Because Egg scrapes the user’s authenticated pages, a channel can resurface walled-garden content (their own LinkedIn / YouTube / X posts) as an open feed. A channel over the user’s own posts defaults to public; anything surfacing others’ content is private and never leaves the machine.
• Feed host (feeds.host): status(), connect(handle), republish(), disconnect(), setAdvanced(cfg) — give the user’s public feeds an always-on public address they own. connect claims a handle on a feed host, pushes the existing public feeds, and returns the public base URL; every later publish pushes again, and updates are instant (rssCloud). The token stays server-side.

EggletContext.explorations

Hub-and-spoke exploration graphs — the Ponder / Explore domain. An exploration is a tree of nodes (prompts, responses, images) anchored to a source; any Egglet can create and extend them.

• Explorations: list(opts?), get(id), create(req), patch(id, patch), remove(id).
• Nodes: addNode(explorationId, req), patchNode(nodeId, patch), reparentNode(nodeId, newParentId), removeNode(nodeId).
• publish(id, { title, description?, includeSourceText? }) — publish to the cloud as a shareable view; resolves to { id, url } where url is the viewer path (/view/exploration/<id>).

EggletContext.people

The contacts domain — the single write surface for the People tables (entity + profile + work history + education). The People app and the Egg Extension ingest through this same implementation, so a profile captured from a social page and one added by hand land in the same place. Gated to the People Egglet and the agent.

• Read: list({ query?, limit? }), get(id), search(query, limit?).
• Write: create(person) → id, update(id, patch).
• ingestProfile(profile) — upsert a scraped/structured profile; returns { entityId, created }. The path the extension uses.
• Dedup: duplicates() — name-matched, scored candidate pairs; merge(survivorId, duplicateId) — move the duplicate’s profiles / work history / posts onto the survivor, fill empty survivor fields, delete the duplicate, and return the survivor.

EggletContext.artifacts

Long-lived domain artifacts: code, documents, diagrams. Distinct from files, which surfaces ephemeral generated media. Artifacts are durable, addressable by id, and round-trip through sync.

EggletContext.agent

The persistent Egg agent’s own self and state — separate from ctx.ai, which is stateless inference. Where ctx.ai asks a model a question, ctx.agent reads and writes the standing agent: what it remembers, how it spends its time, who it is, and what it can do. It binds to the primary agent, so the agent id is implicit (ctx.agent.id is "agent-primary"). Every call routes through the Gateway, which owns the agent.

Seven sub-surfaces: chat, calendar, personality, memory, workspaces, tools, skills. Data shapes are the Gateway’s own (snake_case), returned verbatim.

// Review and prune what the agent remembers.
const notes = await ctx.agent.memory.list({ category: "preference", limit: 50 });
await ctx.agent.memory.add({ content: "Prefers concise answers.", category: "preference" });
await ctx.agent.memory.remove(notes[0].id);

// Ask the standing agent (full personality + memory + tools), not a bare model.
const reply = await ctx.agent.chat({
  messages: [{ role: "user", content: "What are you working on?" }],
  latest: "What are you working on?",
});

EggletContext.agent.chat

EggletContext.agent.memory

The agent’s long-term memory — the store it extracts on its own from conversations and background thinking, and reads back into its system prompt. This is not the Memorize Egglet’s knowledge base.

EggletContext.agent.calendar

The agent’s time allocation and autonomy. Standing reservations materialize into concrete time blocks each day, which the Gateway’s block runner executes during the agent’s private window; the soft plan is its forward-look.

• listBlocks({ from?, to? }) → AgentTimeBlock[]; cancelBlock(id).
• listReservations() → StandingReservation[]; createReservation(req), updateReservation(id, patch), deleteReservation(id).
• getPrivateTime() / setPrivateTime({ start, end }) — the daily off-hours window ("HH:MM", or null for none).
• getSoftPlan() → SoftPlanRow[] (parse allocations_json); materialize() turns standing reservations into today’s blocks; planNow() runs a planning pass.

EggletContext.agent.personality

The four markdown documents that shape the agent (identity, motivations, goals, standards). getFile(filename) → { content, filename }; setFile(filename, content) writes it back. Changes take effect on the next turn.

EggletContext.agent.workspaces, .tools, .skills

• workspaces.list() → WorkspaceSummary[]; workspaces.setActive(id | null).
• tools.list() → AgentToolRow[]; tools.set(name, enabled) assigns/enables a tool for the agent.
• skills.list() → AgentSkillRow[]; skills.set(slug, enabled) assigns/enables a skill.

EggletContext.gateway

A deliberate escape hatch: low-level authorized access to the local Gateway, for first-party Egglets that need an endpoint not yet wrapped by a typed ctx.* surface. It is subject to the same authorization as every other ctx call — the Egglet’s per-origin scoped bearer token is attached automatically, and an endpoint that token may not reach still returns 403.

Prefer a typed surface wherever one exists; reach for this only when none does, and expect the call site to migrate to a typed surface later. (This is how the Agent app reached its calendar / personality / tools before ctx.agent existed.)

• url — base URL of the local Gateway this Egglet is bound to.
• fetch(path, init?) — authorized fetch; path (e.g. /api/agents) is appended to url and the bearer token attached. Returns a standard Response.