@odyn-app/api 0.2.1 → 0.3.0

package/README.md

@@ -29,8 +29,77 @@ defineExtension({
 - `@odyn-app/api/ui`: Odyn's `Button`, `Skeleton`, `SettingRow`, `Orb` and `cn`, for extension pages.
 - `@odyn-app/api/theme.css`: Odyn's colours, fonts and light/dark themes. Add `@import "@odyn-app/api/theme.css";` to a page's stylesheet.
 
+## A sidebar button, a full-window page and a dashboard card (kit version 5)
+
+With `apiVersion: 5`, any extension can ask for these. The user approves each one at install.
+
+- `ui:sidebar` + `sidebarItem: { title, icon, command }` — a button under Marketplace. A click runs `command`. `odyn.ui.setBadge(3)` shows a number on it; `null` or `0` clears it.
+- `ui:dialog` + a page in `surfaces` with `placement: 'dialog'` — a full-window page. `odyn.ui.openDialog()` opens it, but only while handling a click on your button or card.
+- `ui:dashboard` + `dashboardCard: { command }` — one card on the dashboard. Return `{ type: 'card', title, items, actions }` from `command`, or call `odyn.dashboard.setCard(card)` at any time (`null` hides it). Clicking an item or action runs `command` again with `itemId` or `actionId`.
+
+```ts
+defineExtension({
+  commands: {
+    'open-board': async ({ odyn }) => { await odyn.ui.openDialog() },
+    'refresh-card': async ({ odyn, actionId }) => {
+      if (actionId === 'open') await odyn.ui.openDialog()
+      await odyn.ui.setBadge(2)
+      return { type: 'card', title: 'Standup', items: [{ id: 'a', title: 'Two updates waiting' }], actions: [{ id: 'open', title: 'Open board' }] }
+    },
+  },
+})
+```
+
 Every extension runs sandboxed, and each call is checked against the permissions the user granted.
 
+## Shared storage and who called a tool (kit version 6)
+
+With `apiVersion: 6`, no extra permission needed:
+
+- `odyn.storage` in your commands, and `surface.storage` in your pages: one text store for the whole extension. `get(key)`, `set(key, value)` (`null` removes it) and `keys(prefix?)`. Save JSON as text. Each value can be up to 5 MB, and 50 MB altogether. Everything is deleted when the extension is uninstalled.
+- `ui:dialog` + `composerMenuItem: { title, icon, command }` (kit version 6) — an entry in the message box's + menu, e.g. "Attach initiative". A click runs `command`, told which chat through `caller`.
+- `odyn.ui.openDialog({ chatId?, item? })` (kit version 6) opens your page for a chat and at one of your own items, e.g. `{ chatId: caller.chatId, item: planId }`. The page reads both from its context (`context.chatId`, `context.item`). With no options it opens as before.
+- `odyn.chats.list()` and `chats.current()` also say `isWorking` (the agent is mid-reply) and `workspaceChatId` (the workspace's main chat, shared by every chat in that workspace). Both are missing on older Odyn versions.
+- `ui:chatHeader` + `chatChip: { command }` (kit version 6) — a small label with a coloured dot next to a chat's title. `odyn.ui.setChatChip(chatId, { label, color? })` sets it for one chat (label up to 40 characters; colour `gray`, `blue`, `green`, `amber`, `red` or `purple`); `null` removes it. A click runs `command`, told which chat through `caller`, and may open your page.
+- Ask-first cards (kit version 6, no extra permission): an `agentTool` command may answer with a card that has one or two `actions`, e.g. "This looks like part of X — [Not now] [Link chat]". Odyn shows it in the chat under the tool call and tells the agent to wait. Nothing happens until the person clicks: the click runs the same command again with the same `input` and the button's id in `actionId`, and `caller` set to the chat. Each card can be answered once; if your command fails, the card opens again. Card buttons can't use `opensDialog` — call `odyn.ui.openDialog()` instead.
+- A command with `placement: 'chatContext'` (one per extension, `agent:context` permission, kit version 6) is never shown. Odyn runs it when a chat starts a fresh session and after a long chat is summed up, telling it the caller like an agent tool. Its answer (text, or any view, read as text) goes in front of the user's message, cut to 2,000 characters. Answer within 2 seconds or the message goes without it; return `null` to add nothing.
+- `odyn.notes.run(tool, target, input)` (and `surface.notes.run` in pages), Odyn's own extensions only: runs one of Odyn's note and initiative tools. With a chat id as `target` it runs as if that chat's agent called it; with `{ projectId }` it runs for the person on your page (no chat needed, changes are recorded as theirs, and chat-only extras such as a card in the chat are skipped). Either way it takes the same input and the same team-sharing rules, and returns `{ text, isError }`. `ListNotes`, `ReadNote`, `ListInitiatives` and `ReadInitiative` need `notes:read`; `CreateNote`, `EditNote`, `PatchNote`, `RenameNote`, `DeleteNote`, `CreateInitiative`, `MoveNotesToInitiative`, `MarkInitiativeComplete`, `EditInitiativeArtifacts` and `EditInitiativeGroups` need `notes:write`. Kit version 6.
+- `odyn.notes.list(projectId)`, `odyn.notes.initiative(projectId, initiativeId)` and `odyn.notes.read(projectId, noteId)` (and the same on `surface.notes`), Odyn's own extensions only, need `notes:read`: structured reads for your page. `list` gives the project's initiatives and its loose notes (notes in no initiative), `initiative` one initiative's groups and documents in order (`null` if it isn't in that project), `read` one note as markdown with its `version` (pass that to `EditNote` / `PatchNote` so a newer copy is never overwritten). Same team-sharing rules as the tools.
+- In pages (kit version 6), `surface.chats.list(projectId?)`, `surface.projects.list()` and `surface.ui.setChatChip(chatId, chip)` work the same as their `odyn.` versions, with the same `chats:read` / `projects:read` / `ui:chatHeader` permissions.
+- An agent tool's context has `caller: { chatId, projectId, workspaceChatId, kind }` saying which chat (or `kind: 'spryte'` for Odyn's coordinating agent) called it. `workspaceChatId` is shared by every chat in one workspace. It is missing for clicks.
+
+```ts
+defineExtension({
+  commands: {
+    'link-chat': async ({ odyn, caller, input }) => {
+      if (!caller) return 'Only an agent can link its chat.'
+      await odyn.storage.set(`link:${caller.workspaceChatId}`, JSON.stringify({ planId: input.planId }))
+      return 'Linked.'
+    },
+  },
+})
+```
+
+## Screenshots
+
+Add `screenshots` to the `odyn` section of `package.json` to show a strip of pictures on your extension's page in Odyn's Marketplace. With none, Odyn shows a placeholder with your icon.
+
+```json
+"screenshots": ["screenshots/1.png", "screenshots/2.webp"]
+```
+
+- Up to 5, each a path inside your extension's folder.
+- `.png`, `.jpg`, `.jpeg` or `.webp`, at most 1 MB each.
+- Forward slashes only; no `..`, no paths starting with `/` or a drive like `C:`, and no web addresses.
+
+`odyn-extension check` (and `build` and `publish`) makes sure every file is there and small enough.
+
+## Feedback
+
+People can send feedback (a bug, an idea or a question, with an optional screenshot) and give a thumbs up from your extension's page in Odyn. Feedback arrives anonymously as a GitHub issue on [New-Genre/odyn-extensions](https://github.com/New-Genre/odyn-extensions/issues), labelled `ext:<your id>` plus the kind, and mentions your extension's `owners`.
+
+Answer by commenting on the issue — the sender sees your replies inside Odyn under "Your feedback". Closing the issue shows it to them as closed. The sender is anonymous, so never ask for personal details in a reply.
+
 **[Read the docs](https://www.odyn.build/docs/extensions)** for what extensions can and can't do, every permission and limit, and the full reference. To publish one to Odyn's Marketplace, see the [contribution guide](https://github.com/New-Genre/odyn-extensions/blob/main/CONTRIBUTING.md).
 
 MIT licence.

package/cli/build.mjs

@@ -10,12 +10,12 @@
  * Every manifest is checked with the same checker Odyn runs on a download,
  * so a broken one fails here rather than on someone's Mac.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/postcss'
 import { build } from 'vite'
-import { validateManifest } from '../dist/index.js'
+import { MAX_EXTENSION_SCREENSHOT_BYTES, validateManifest } from '../dist/index.js'
 
 const PANEL_DIR = join('dist', 'panel')
 const HELPER_SOURCE = join('src', 'helper.ts')
@@ -43,7 +43,22 @@ export function checkExtension(sourceDir, { official = false } = {}) {
   const problems = []
   if (pkg.private !== true) problems.push('"private": true is required, so it is never published to npm by mistake.')
   const manifest = { ...pkg.odyn, version: pkg.version }
-  problems.push(...validateManifest(manifest, { official }))
+  const manifestProblems = validateManifest(manifest, { official })
+  problems.push(...manifestProblems)
+  // The paths themselves are only worth looking for once the manifest is sound.
+  if (manifestProblems.length === 0) problems.push(...screenshotFileProblems(sourceDir, manifest.screenshots ?? []))
+  return problems
+}
+
+/** Checks every screenshot the manifest lists is a real picture file of at most 1 MB. */
+function screenshotFileProblems(sourceDir, screenshots) {
+  const problems = []
+  for (const path of screenshots) {
+    const file = join(sourceDir, path)
+    const info = existsSync(file) ? statSync(file) : null
+    if (!info?.isFile()) problems.push(`Screenshot "${path}" was not found in this folder.`)
+    else if (info.size > MAX_EXTENSION_SCREENSHOT_BYTES) problems.push(`Screenshot "${path}" is bigger than 1 MB.`)
+  }
   return problems
 }
 

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 /** The newest building-kit version. Bumped when something new is added. */
-export declare const EXTENSION_API_VERSION = 4;
+export declare const EXTENSION_API_VERSION = 6;
 /** The oldest building-kit version Odyn still runs. */
 export declare const EXTENSION_API_MIN_VERSION = 1;
 /** Everything an extension can ask the user to allow. */
-export declare const EXTENSION_PERMISSIONS: readonly ["chats:read", "projects:read", "agents:start", "network", "composer:attach", "screenshots:read", "programs:run", "agent:tools"];
+export declare const EXTENSION_PERMISSIONS: readonly ["chats:read", "projects:read", "agents:start", "network", "composer:attach", "screenshots:read", "programs:run", "agent:tools", "ui:sidebar", "ui:dialog", "ui:dashboard", "notes:read", "notes:write", "agent:context", "ui:chatHeader"];
 export type ExtensionPermission = (typeof EXTENSION_PERMISSIONS)[number];
 /** Permissions only extensions made by Odyn may ask for. */
 export declare const OFFICIAL_ONLY_PERMISSIONS: readonly ExtensionPermission[];
@@ -18,9 +18,18 @@ export declare function isOdynExtensionId(id: string): boolean;
 /** Systems an extension can say it runs on. Leave out to run everywhere. */
 export declare const EXTENSION_PLATFORMS: readonly ["darwin", "linux", "win32"];
 export type ExtensionPlatform = (typeof EXTENSION_PLATFORMS)[number];
-/** Where an extension can show up inside Odyn. */
-export declare const EXTENSION_PLACEMENTS: readonly ["sidebarPanel", "chatCard", "agentTool", "settings"];
+/**
+ * Where an extension can show up inside Odyn. `chatContext` (kit version 6,
+ * `agent:context`) is never shown: Odyn runs it when a chat starts, and after
+ * a long chat is summed up, and puts its short text answer in front of the
+ * user's message.
+ */
+export declare const EXTENSION_PLACEMENTS: readonly ["sidebarPanel", "chatCard", "agentTool", "settings", "chatContext"];
 export type ExtensionPlacement = (typeof EXTENSION_PLACEMENTS)[number];
+/** The most a `chatContext` command's answer may add to a message; anything longer is cut. */
+export declare const EXTENSION_CONTEXT_MAX_CHARS = 2000;
+/** How long Odyn waits for a `chatContext` command before sending the message without it. */
+export declare const EXTENSION_CONTEXT_TIMEOUT_MS = 2000;
 export interface ExtensionCommand {
     /** Unique within the extension, e.g. "show-standup". */
     readonly name: string;
@@ -46,11 +55,18 @@ export interface ExtensionCommandInput {
 /** A value the agent or a form handed to a command. */
 export type ExtensionInputValue = string | number | boolean;
 /** Where an extension's own page can be shown. */
-export declare const EXTENSION_SURFACE_PLACEMENTS: readonly ["composer", "settings"];
+export declare const EXTENSION_SURFACE_PLACEMENTS: readonly ["composer", "settings", "dialog"];
 export type ExtensionSurfacePlacement = (typeof EXTENSION_SURFACE_PLACEMENTS)[number];
 /** The icons Odyn can draw on the button that opens a page. */
 export declare const EXTENSION_SURFACE_ICONS: readonly ["puzzle", "pencil", "image", "note"];
 export type ExtensionSurfaceIcon = (typeof EXTENSION_SURFACE_ICONS)[number];
+/**
+ * The icons an extension can pick for itself in the Marketplace list and on
+ * its page. Any name Odyn doesn't know (say, one added in a newer Odyn) shows
+ * the puzzle piece instead, so it never stops an extension installing.
+ */
+export declare const EXTENSION_ICONS: readonly ["puzzle", "pencil", "image", "note", "inbox", "cursor", "palette", "globe", "phone", "list"];
+export type ExtensionIcon = (typeof EXTENSION_ICONS)[number];
 export declare const SURFACE_MIN_HEIGHT = 120;
 export declare const SURFACE_MAX_HEIGHT = 600;
 /**
@@ -63,7 +79,9 @@ export interface ExtensionSurface {
     readonly title: string;
     /**
      * `composer`: slides open above the message box, with a toolbar button.
-     * `settings`: shown inside the extension's settings window.
+     * `settings`: shown inside the extension's settings page.
+     * `dialog`: fills a full-window dialog, opened only after a click (see
+     * `odyn.ui.openDialog`). Needs `apiVersion` 5 and the `ui:dialog` permission.
      */
     readonly placement: ExtensionSurfacePlacement;
     /** The page inside the extension's folder, e.g. "dist/panel/index.html". */
@@ -72,6 +90,47 @@ export interface ExtensionSurface {
     /** Height in pixels. Defaults to 260. */
     readonly height?: number;
 }
+/** A button in Odyn's sidebar, under "Marketplace". Clicking it runs `command`. */
+export interface ExtensionSidebarItem {
+    readonly title: string;
+    readonly icon: ExtensionSurfaceIcon;
+    /** A command in `commands`. It may call `odyn.ui.openDialog()`. */
+    readonly command: string;
+}
+/**
+ * An entry in the message box's + menu (kit version 6, `ui:dialog`). Clicking
+ * it runs `command`, told which chat it is through `caller`, so the command can
+ * open the extension's page for that chat with `odyn.ui.openDialog({ chatId })`.
+ */
+export interface ExtensionComposerMenuItem {
+    readonly title: string;
+    readonly icon: ExtensionSurfaceIcon;
+    /** A command in `commands`. It may call `odyn.ui.openDialog()`. */
+    readonly command: string;
+}
+/** The chip next to a chat's title. Clicking it runs `command`, told which chat it is. */
+export interface ExtensionChatChipSource {
+    /** A command in `commands`. It may call `odyn.ui.openDialog()`. */
+    readonly command: string;
+}
+/** The colours a chat chip's dot can be. Odyn picks the exact shade for the theme. */
+export declare const EXTENSION_CHIP_COLORS: readonly ["gray", "blue", "green", "amber", "red", "purple"];
+export type ExtensionChipColor = (typeof EXTENSION_CHIP_COLORS)[number];
+/** The longest label a chat chip can carry. */
+export declare const CHAT_CHIP_MAX_LABEL = 40;
+/** What a chat chip shows: a short label and a coloured dot. */
+export interface ExtensionChatChip {
+    readonly label: string;
+    /** Leave out for gray. */
+    readonly color?: ExtensionChipColor;
+}
+/** Why a chat chip can't be drawn. An empty list means it is fine. */
+export declare function chatChipProblems(value: unknown): readonly string[];
+/** Where a dashboard card comes from: Odyn runs `command` whenever the dashboard opens. */
+export interface ExtensionDashboardCardSource {
+    /** A command in `commands` that returns `{ type: 'card', … }`, or nothing to hide the card. */
+    readonly command: string;
+}
 export interface ExtensionPreference {
     readonly name: string;
     readonly title: string;
@@ -106,6 +165,13 @@ export interface ExtensionHelper {
     readonly links?: readonly string[];
     /** Hosts `download` may fetch from (redirects must stay inside the list). */
     readonly downloadHosts?: readonly string[];
+    /**
+     * Page calls (names given to `odyn.pages.handle`) that only look and never
+     * change anything, e.g. "setupStatus". Only these may be asked for from a
+     * page opened in a browser through Web Access; every other call stays on
+     * the Mac running Odyn.
+     */
+    readonly browserSafeCalls?: readonly string[];
 }
 /** A command the agent must ask before using, e.g. `{ program: 'xcrun', subcommand: 'simctl' }`. */
 export interface ExtensionGatedCommand {
@@ -150,11 +216,28 @@ export interface ExtensionManifest {
     readonly helper?: ExtensionHelper;
     /** A guide and permission-checked commands for the agent. */
     readonly agent?: ExtensionAgent;
+    /** Its icon in the Marketplace, one of `EXTENSION_ICONS`. Defaults to the puzzle piece. */
+    readonly icon?: ExtensionIcon;
     /**
      * GitHub usernames of the people who look after it. Changes to the
      * extension in the public repo need one of them (or Odyn) to approve.
      */
     readonly owners?: readonly string[];
+    /**
+     * Pictures of the extension, shown as a strip on its page in Odyn's
+     * Marketplace. Each is a path inside the extension's folder, e.g.
+     * "screenshots/1.png" — up to 5, each a .png, .jpg, .jpeg or .webp file of
+     * at most 1 MB. With none, Odyn shows a placeholder with the icon.
+     */
+    readonly screenshots?: readonly string[];
+    /** A button in Odyn's sidebar. Needs `apiVersion` 5 and `ui:sidebar`. */
+    readonly sidebarItem?: ExtensionSidebarItem;
+    /** A card on Odyn's dashboard. Needs `apiVersion` 5 and `ui:dashboard`. */
+    readonly dashboardCard?: ExtensionDashboardCardSource;
+    /** An entry in the message box's + menu. Needs `apiVersion` 6 and `ui:dialog`. */
+    readonly composerMenuItem?: ExtensionComposerMenuItem;
+    /** A chip next to chats' titles, set per chat with `odyn.ui.setChatChip`. Needs `apiVersion` 6 and `ui:chatHeader`. */
+    readonly chatChip?: ExtensionChatChipSource;
 }
 export interface ExtensionAction {
     readonly id: string;
@@ -168,11 +251,34 @@ export interface ListItem {
     readonly accessory?: string;
     readonly actions?: readonly ExtensionAction[];
 }
+export declare const DASHBOARD_CARD_MAX_ITEMS = 5;
+export declare const DASHBOARD_CARD_MAX_ACTIONS = 2;
+export declare const DASHBOARD_CARD_MAX_TITLE = 80;
+export declare const DASHBOARD_CARD_MAX_SUBTITLE = 140;
+export interface DashboardCardItem {
+    readonly id: string;
+    readonly title: string;
+    readonly subtitle?: string;
+}
+export interface DashboardCardAction {
+    readonly id: string;
+    readonly title: string;
+    /** Opens the extension's `dialog` page straight away, without running code. */
+    readonly opensDialog?: boolean;
+}
+/** The card Odyn draws on its dashboard: a few updates or to-dos, and up to two buttons. */
+export interface ExtensionDashboardCard {
+    readonly title: string;
+    readonly items: readonly DashboardCardItem[];
+    readonly actions?: readonly DashboardCardAction[];
+}
 export type ExtensionView = {
     readonly type: 'list';
     readonly items: readonly ListItem[];
     readonly emptyText?: string;
-} | {
+} | ({
+    readonly type: 'card';
+} & ExtensionDashboardCard) | {
     readonly type: 'detail';
     readonly markdown: string;
     readonly actions?: readonly ExtensionAction[];
@@ -190,6 +296,14 @@ export interface ChatSummary {
     readonly projectId: string;
     readonly title: string;
     readonly updatedAt: string;
+    /** True while the chat's agent is in the middle of a reply. Odyn 2026-11 and later. */
+    readonly isWorking?: boolean;
+    /**
+     * The workspace's main chat. Every chat in one workspace shares it, so it is
+     * the key for anything that should apply to the whole workspace. Odyn
+     * 2026-11 and later.
+     */
+    readonly workspaceChatId?: string;
 }
 export interface ProjectSummary {
     readonly id: string;
@@ -201,6 +315,14 @@ export interface ChatMessageSummary {
     readonly createdAt: string;
 }
 /** Odyn's side of the conversation. Every call is permission-checked by Odyn. */
+/** An extension's own shared storage (kit version 6). Save JSON as text. */
+export interface ExtensionStorage {
+    get(key: string): Promise<string | null>;
+    /** `null` removes the value. */
+    set(key: string, value: string | null): Promise<void>;
+    /** Keys that start with `prefix` (all of them when left out), in order. */
+    keys(prefix?: string): Promise<readonly string[]>;
+}
 export interface OdynApi {
     readonly chats: {
         list(projectId?: string): Promise<readonly ChatSummary[]>;
@@ -227,15 +349,168 @@ export interface OdynApi {
     showToast(message: string): Promise<void>;
     /** The values the user saved in the extension's settings. */
     preferences(): Promise<Readonly<Record<string, string | boolean>>>;
+    readonly ui: {
+        /**
+         * Opens the extension's `dialog` page. Only works while a command started
+         * by a click (the sidebar button, a dashboard card, a chat chip or the
+         * message box's + menu) is running. From kit version 6 it can say which
+         * chat and which item to show; the page reads them from its context.
+         */
+        openDialog(options?: ExtensionDialogOptions): Promise<void>;
+        /** The number on the sidebar button. `null` or 0 clears it. */
+        setBadge(count: number | null): Promise<void>;
+        /** The chip next to this chat's title. `null` removes it. Needs `ui:chatHeader` and a `chatChip`. */
+        setChatChip(chatId: string, chip: ExtensionChatChip | null): Promise<void>;
+    };
+    readonly dashboard: {
+        /** Replaces the dashboard card at any time. `null` hides it. */
+        setCard(card: ExtensionDashboardCard | null): Promise<void>;
+    };
+    /**
+     * The extension's own shared storage: text values by key, kept for the whole
+     * extension rather than one chat, and readable from its pages too. Cleared
+     * when the extension is uninstalled. Needs `apiVersion` 6; no permission.
+     */
+    readonly storage: ExtensionStorage;
+    /**
+     * Odyn's note and initiative tools, run as if the given chat's agent called
+     * them, under the same team visibility rules. Read tools need `notes:read`,
+     * the rest `notes:write`. Kit version 6.
+     */
+    readonly notes: ExtensionNotesApi;
+}
+/** The note and initiative tools that only look. */
+export declare const EXTENSION_NOTE_READ_TOOLS: readonly ["ListNotes", "ReadNote", "ListInitiatives", "ReadInitiative"];
+/** The note and initiative tools that change something. */
+export declare const EXTENSION_NOTE_WRITE_TOOLS: readonly ["CreateNote", "EditNote", "PatchNote", "RenameNote", "DeleteNote", "CreateInitiative", "MoveNotesToInitiative", "MarkInitiativeComplete", "EditInitiativeArtifacts", "EditInitiativeGroups"];
+export type ExtensionNoteTool = (typeof EXTENSION_NOTE_READ_TOOLS)[number] | (typeof EXTENSION_NOTE_WRITE_TOOLS)[number];
+/** What a note tool answered: the same text an agent would see. */
+export interface ExtensionNoteToolResult {
+    readonly text: string;
+    readonly isError: boolean;
+}
+/**
+ * Who a note tool works for. A chat id runs it as that chat's agent: the chat
+ * picks the project, and changes are recorded as the agent's. `{ projectId }`
+ * runs it for the person on the extension's own page, where there is no chat:
+ * changes are recorded as theirs, and chat-only extras (a card in the chat,
+ * attaching the chat's workspace) are skipped. The id is a chat's `projectId`
+ * (from `chats.list` or `projects.list`).
+ */
+export type ExtensionNoteTarget = string | {
+    readonly projectId: string;
+};
+/** Where an initiative is in its life. */
+export type ExtensionInitiativeStatus = 'active' | 'shipped' | 'archived';
+/** One initiative in a project's list. */
+export interface ExtensionInitiativeSummary {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string | null;
+    readonly status: ExtensionInitiativeStatus;
+    readonly documentCount: number;
+    readonly updatedAt: string;
+}
+/** A note that is not in any initiative. */
+export interface ExtensionLooseNote {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string | null;
+    readonly updatedAt: string;
+    readonly visibility: 'private' | 'team';
+}
+/** A project's initiatives and loose notes, as the person may see them. */
+export interface ExtensionNotesList {
+    readonly initiatives: readonly ExtensionInitiativeSummary[];
+    readonly notes: readonly ExtensionLooseNote[];
+    /** Why the synced half could not be read (the list is then this machine's notes only); null when complete. */
+    readonly degraded: string | null;
+}
+/** A named stretch of an initiative's documents. */
+export interface ExtensionInitiativeGroup {
+    readonly id: string;
+    readonly name: string;
+    /** Where new documents go by default. At most one group is active. */
+    readonly active: boolean;
+    readonly done: boolean;
+}
+/** One document in an initiative, without its body. */
+export interface ExtensionInitiativeDocument {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string | null;
+    readonly updatedAt: string;
+    /** Who changed it last; null when unknown. */
+    readonly updatedBy: 'user' | 'agent' | null;
+    /** Changed since the person last opened it on this machine. */
+    readonly updatedSinceSeen: boolean;
+    /** Its group; null when ungrouped. */
+    readonly groupId: string | null;
+}
+/** One initiative with its groups and documents, in order. */
+export interface ExtensionInitiative {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string | null;
+    readonly status: ExtensionInitiativeStatus;
+    readonly createdAt: string;
+    readonly groups: readonly ExtensionInitiativeGroup[];
+    readonly documents: readonly ExtensionInitiativeDocument[];
+}
+/** A note or document read as markdown. */
+export interface ExtensionNote {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string | null;
+    readonly visibility: 'private' | 'team';
+    readonly updatedAt: string;
+    readonly markdown: string;
+    /** A document's version: pass it to `EditNote` / `PatchNote` so a newer copy is never overwritten. Null for other notes. */
+    readonly version: number | null;
+    /** Why this machine's copy was read rather than the server's; null when fresh. */
+    readonly offline: string | null;
+}
+export interface ExtensionNotesApi {
+    /** Runs one note tool for a chat or a project, with the tool's usual input. */
+    run(tool: ExtensionNoteTool, target: ExtensionNoteTarget, input: Readonly<Record<string, unknown>>): Promise<ExtensionNoteToolResult>;
+    /** A project's initiatives and loose notes, for a page. Needs `notes:read`. */
+    list(projectId: string): Promise<ExtensionNotesList>;
+    /** One initiative with its groups and documents, or null when it is not in that project. Needs `notes:read`. */
+    initiative(projectId: string, initiativeId: string): Promise<ExtensionInitiative | null>;
+    /** One note or document as markdown, or null when it is not in that project. Needs `notes:read`. */
+    read(projectId: string, noteId: string): Promise<ExtensionNote | null>;
 }
 /** What a command receives when it runs. */
 export interface CommandContext {
     readonly odyn: OdynApi;
-    /** Set when the user picked an action on something the command drew. */
+    /**
+     * Set when the user picked an action on something the command drew. For an
+     * agent tool, set when the person clicked a button on the chat card the tool
+     * answered with — `input` is then the tool's original input, and `caller`
+     * the chat the card is in (kit version 6).
+     */
     readonly actionId?: string;
     readonly itemId?: string;
     /** Set when a form was submitted, or the agent called an agent tool. */
     readonly input?: Readonly<Record<string, ExtensionInputValue>>;
+    /**
+     * Who called this agent tool: their chat, project and workspace. Missing
+     * for clicks, and for agents Odyn cannot tie to one chat. Kit version 6.
+     */
+    readonly caller?: ExtensionToolCaller;
+}
+/** The chat whose agent called an agent tool. */
+export interface ExtensionToolCaller {
+    readonly chatId: string;
+    readonly projectId: string;
+    /**
+     * The workspace's main chat. Every chat in one workspace (a folder of work
+     * with its own branch) shares it, so it is the key to use for anything that
+     * should apply to the whole workspace. A chat with no workspace is its own.
+     */
+    readonly workspaceChatId: string;
+    /** `spryte` when a Spryte (Odyn's coordinating agent) is calling. */
+    readonly kind: 'chat' | 'spryte';
 }
 /** Draws a view, or (for an agent tool) returns text for the agent. */
 export type CommandHandler = (context: CommandContext) => Promise<ExtensionView | string | void>;
@@ -249,6 +524,8 @@ export interface ExtensionRunRequest {
     readonly actionId?: string;
     readonly itemId?: string;
     readonly input?: Readonly<Record<string, ExtensionInputValue>>;
+    /** Who called an agent tool; see `CommandContext.caller`. */
+    readonly caller?: ExtensionToolCaller;
 }
 export type ExtensionRunResult = {
     readonly ok: true;
@@ -264,7 +541,7 @@ export interface ExtensionBridge {
     finish(callId: string, result: ExtensionRunResult): void;
 }
 /** Every method name the bridge accepts, so Odyn can refuse anything else. */
-export declare const EXTENSION_API_METHODS: readonly ["chats.list", "chats.messages", "chats.current", "projects.list", "agents.start", "fetch", "showToast", "preferences"];
+export declare const EXTENSION_API_METHODS: readonly ["chats.list", "chats.messages", "chats.current", "projects.list", "agents.start", "fetch", "showToast", "preferences", "ui.openDialog", "ui.setBadge", "ui.setChatChip", "dashboard.setCard", "storage.get", "storage.set", "storage.keys", "notes.run", "notes.get"];
 export type ExtensionApiMethod = (typeof EXTENSION_API_METHODS)[number];
 /**
  * The one call an extension's entry file makes. Inside Odyn it hooks the
@@ -272,6 +549,23 @@ export type ExtensionApiMethod = (typeof EXTENSION_API_METHODS)[number];
  * hands the definition back.
  */
 export declare function defineExtension(definition: ExtensionDefinition): ExtensionDefinition;
+/** The most pictures a manifest's `screenshots` may list. */
+export declare const MAX_EXTENSION_SCREENSHOTS = 5;
+/** The biggest a single screenshot file may be: 1 MB. */
+export declare const MAX_EXTENSION_SCREENSHOT_BYTES: number;
+/** The picture types a screenshot may be (compared ignoring capitals). */
+export declare const EXTENSION_SCREENSHOT_EXTENSIONS: readonly string[];
+/** Why a dashboard card can't be drawn. An empty list means it is fine. */
+export declare function dashboardCardProblems(value: unknown): readonly string[];
+/**
+ * Whether an agent tool's `card` answer can be shown in the chat as a card
+ * the person answers (kit version 6). It is a dashboard card with one or two
+ * buttons; a click runs the same tool again with the button's `actionId`.
+ * Use it to ask before doing something, e.g. "This looks like part of X —
+ * [Not now] [Link chat]". A card that fails these checks reaches the agent
+ * as plain text, as before.
+ */
+export declare function chatCardProblems(value: unknown): readonly string[];
 /** Returns every problem with a manifest; an empty list means it is fine. */
 export interface ManifestCheckOptions {
     /**
@@ -286,15 +580,28 @@ export declare function validateManifest(value: unknown, options?: ManifestCheck
 /** Every message between a page and Odyn carries this tag. */
 export declare const SURFACE_MESSAGE_TAG = "odyn-surface";
 /** Every call a page can make, so Odyn can refuse anything else. */
-export declare const EXTENSION_SURFACE_METHODS: readonly ["chatStorage.get", "chatStorage.set", "composer.attachImage", "helper.call"];
+export declare const EXTENSION_SURFACE_METHODS: readonly ["chatStorage.get", "chatStorage.set", "composer.attachImage", "helper.call", "storage.get", "storage.set", "storage.keys", "notes.run", "notes.get", "chats.list", "projects.list", "ui.setChatChip"];
 export type ExtensionSurfaceMethod = (typeof EXTENSION_SURFACE_METHODS)[number];
 /** The most a page may keep for one chat, and the largest picture it may attach. */
 export declare const SURFACE_STORAGE_MAX_BYTES = 5000000;
+/** The most an extension may keep in its shared `storage` altogether. */
+export declare const EXTENSION_STORAGE_MAX_BYTES = 50000000;
 export declare const SURFACE_IMAGE_MAX_BYTES = 10000000;
+/** The longest `item` a dialog can be opened at. */
+export declare const DIALOG_ITEM_MAX_LENGTH = 200;
+/** Where to open the extension's page (kit version 6). Both are optional. */
+export interface ExtensionDialogOptions {
+    /** The chat the page is for, e.g. the `caller.chatId` of a chip click. */
+    readonly chatId?: string;
+    /** Something of the extension's own to show first, e.g. an initiative id. Plain text. */
+    readonly item?: string;
+}
 /** What the page is showing for. Sent on open and whenever it changes. */
 export interface SurfaceContext {
     readonly chatId: string | null;
     readonly theme: 'light' | 'dark';
+    /** The `item` the page was opened at with `odyn.ui.openDialog`, or `null`. */
+    readonly item?: string | null;
 }
 /** A picture handed over by Odyn (a screenshot) or attached by the page. */
 export interface SurfaceImage {
@@ -349,6 +656,23 @@ export interface OdynSurfaceApi {
         /** `null` removes the value. */
         set(chatId: string, key: string, value: string | null): Promise<void>;
     };
+    /** The extension's shared storage, the same store its own code sees as `odyn.storage`. Needs `apiVersion` 6. */
+    readonly storage: ExtensionStorage;
+    /** Odyn's note and initiative tools; see `OdynApi.notes`. Needs `notes:read` / `notes:write`. */
+    readonly notes: ExtensionNotesApi;
+    /** Chats, the same as `odyn.chats.list` (kit version 6). Needs `chats:read`. */
+    readonly chats: {
+        /** One project's chats when given its id, otherwise every chat. */
+        list(projectId?: string): Promise<readonly ChatSummary[]>;
+    };
+    /** Projects, the same as `odyn.projects.list` (kit version 6). Needs `projects:read`. */
+    readonly projects: {
+        list(): Promise<readonly ProjectSummary[]>;
+    };
+    readonly ui: {
+        /** Puts the extension's chip next to a chat's title, or removes it with `null`; the same as `odyn.ui.setChatChip` (kit version 6). Needs `ui:chatHeader`. */
+        setChatChip(chatId: string, chip: ExtensionChatChip | null): Promise<void>;
+    };
     readonly composer: {
         /** Puts a picture onto the user's message. Needs `composer:attach`. */
         attachImage(image: SurfaceImage): Promise<void>;
@@ -463,6 +787,14 @@ export interface OdynHelperApi {
         /** Sends a message to every open page of this extension. */
         post(message: unknown): Promise<void>;
     };
+    readonly ui: {
+        /** The number on the sidebar button. `null` or 0 clears it. Needs `ui:sidebar`. */
+        setBadge(count: number | null): Promise<void>;
+    };
+    readonly dashboard: {
+        /** Replaces the dashboard card. `null` hides it. Needs `ui:dashboard`. */
+        setCard(card: ExtensionDashboardCard | null): Promise<void>;
+    };
 }
 /** Things that happen, delivered to the helper. */
 export interface HelperEvents {
@@ -483,7 +815,7 @@ export interface HelperDefinition extends HelperEvents {
     start(odyn: OdynHelperApi): Promise<void> | void;
 }
 /** Every call a helper can make, so Odyn can refuse anything else. */
-export declare const EXTENSION_HELPER_METHODS: readonly ["programs.find", "programs.run", "programs.launch", "folders.find", "data.path", "data.download", "data.remove", "data.makeFolder", "openLink", "showToast", "sessions.set", "sessions.frame", "pages.post"];
+export declare const EXTENSION_HELPER_METHODS: readonly ["programs.find", "programs.run", "programs.launch", "folders.find", "data.path", "data.download", "data.remove", "data.makeFolder", "openLink", "showToast", "sessions.set", "sessions.frame", "pages.post", "ui.setBadge", "dashboard.setCard"];
 export type ExtensionHelperMethod = (typeof EXTENSION_HELPER_METHODS)[number];
 /** The events Odyn sends a helper. */
 export declare const EXTENSION_HELPER_EVENTS: readonly ["watch", "unwatch", "input", "close", "agentCommand", "chatClosed", "shutdown", "pageCall"];

package/dist/index.js

@@ -12,7 +12,7 @@
 // Keep it dependency-free: it is shared by Odyn, the store checker and every
 // extension.
 /** The newest building-kit version. Bumped when something new is added. */
-export const EXTENSION_API_VERSION = 4;
+export const EXTENSION_API_VERSION = 6;
 /** The oldest building-kit version Odyn still runs. */
 export const EXTENSION_API_MIN_VERSION = 1;
 // --- Manifest -------------------------------------------------------------
@@ -30,9 +30,23 @@ export const EXTENSION_PERMISSIONS = [
     'programs:run',
     /** Give the agent a guide, and ask before it uses the listed commands. */
     'agent:tools',
+    /** Add a button to Odyn's sidebar (`sidebarItem`) with a number badge. Needs `apiVersion` 5. */
+    'ui:sidebar',
+    /** Open a full-window page (a `dialog` surface) after a click. Needs `apiVersion` 5. */
+    'ui:dialog',
+    /** Show a card on Odyn's dashboard (`dashboardCard`). Needs `apiVersion` 5. */
+    'ui:dashboard',
+    /** Read the project's notes and initiatives. Official extensions only; needs `apiVersion` 6. */
+    'notes:read',
+    /** Create, change, move and delete notes and initiatives, team-shared ones included. Official extensions only; needs `apiVersion` 6. */
+    'notes:write',
+    /** Add a short note to a chat's first message (its `chatContext` command). Needs `apiVersion` 6. */
+    'agent:context',
+    /** Put a chip next to a chat's title (`chatChip`). Needs `apiVersion` 6. */
+    'ui:chatHeader',
 ];
 /** Permissions only extensions made by Odyn may ask for. */
-export const OFFICIAL_ONLY_PERMISSIONS = ['programs:run'];
+export const OFFICIAL_ONLY_PERMISSIONS = ['programs:run', 'notes:read', 'notes:write'];
 /**
  * The extensions made by Odyn. Only these may run Mac programs or a background
  * helper, and only these show as "Official". Everything else in Odyn's
@@ -43,6 +57,7 @@ export const ODYN_EXTENSION_IDS = [
     'computer-use',
     'design-skills',
     'fast-browser',
+    'initiatives',
     'message-outline',
     'phones',
     'scratchpad',
@@ -53,16 +68,67 @@ export function isOdynExtensionId(id) {
 }
 /** Systems an extension can say it runs on. Leave out to run everywhere. */
 export const EXTENSION_PLATFORMS = ['darwin', 'linux', 'win32'];
-/** Where an extension can show up inside Odyn. */
-export const EXTENSION_PLACEMENTS = ['sidebarPanel', 'chatCard', 'agentTool', 'settings'];
+/**
+ * Where an extension can show up inside Odyn. `chatContext` (kit version 6,
+ * `agent:context`) is never shown: Odyn runs it when a chat starts, and after
+ * a long chat is summed up, and puts its short text answer in front of the
+ * user's message.
+ */
+export const EXTENSION_PLACEMENTS = ['sidebarPanel', 'chatCard', 'agentTool', 'settings', 'chatContext'];
+/** The most a `chatContext` command's answer may add to a message; anything longer is cut. */
+export const EXTENSION_CONTEXT_MAX_CHARS = 2_000;
+/** How long Odyn waits for a `chatContext` command before sending the message without it. */
+export const EXTENSION_CONTEXT_TIMEOUT_MS = 2_000;
 /** The kinds of value an agent tool's input can take. */
 export const EXTENSION_INPUT_TYPES = ['string', 'number', 'boolean'];
 /** Where an extension's own page can be shown. */
-export const EXTENSION_SURFACE_PLACEMENTS = ['composer', 'settings'];
+export const EXTENSION_SURFACE_PLACEMENTS = ['composer', 'settings', 'dialog'];
 /** The icons Odyn can draw on the button that opens a page. */
 export const EXTENSION_SURFACE_ICONS = ['puzzle', 'pencil', 'image', 'note'];
+/**
+ * The icons an extension can pick for itself in the Marketplace list and on
+ * its page. Any name Odyn doesn't know (say, one added in a newer Odyn) shows
+ * the puzzle piece instead, so it never stops an extension installing.
+ */
+export const EXTENSION_ICONS = [...EXTENSION_SURFACE_ICONS, 'inbox', 'cursor', 'palette', 'globe', 'phone', 'list'];
 export const SURFACE_MIN_HEIGHT = 120;
 export const SURFACE_MAX_HEIGHT = 600;
+/** The colours a chat chip's dot can be. Odyn picks the exact shade for the theme. */
+export const EXTENSION_CHIP_COLORS = ['gray', 'blue', 'green', 'amber', 'red', 'purple'];
+/** The longest label a chat chip can carry. */
+export const CHAT_CHIP_MAX_LABEL = 40;
+/** Why a chat chip can't be drawn. An empty list means it is fine. */
+export function chatChipProblems(value) {
+    if (typeof value !== 'object' || value === null)
+        return ['The chip is not an object.'];
+    const chip = value;
+    const problems = [];
+    if (typeof chip.label !== 'string' || chip.label.trim() === '' || chip.label.length > CHAT_CHIP_MAX_LABEL) {
+        problems.push(`The chip needs a label of at most ${CHAT_CHIP_MAX_LABEL} characters.`);
+    }
+    if (chip.color !== undefined && !EXTENSION_CHIP_COLORS.includes(chip.color))
+        problems.push('The chip has an unknown colour.');
+    return problems;
+}
+export const DASHBOARD_CARD_MAX_ITEMS = 5;
+export const DASHBOARD_CARD_MAX_ACTIONS = 2;
+export const DASHBOARD_CARD_MAX_TITLE = 80;
+export const DASHBOARD_CARD_MAX_SUBTITLE = 140;
+/** The note and initiative tools that only look. */
+export const EXTENSION_NOTE_READ_TOOLS = ['ListNotes', 'ReadNote', 'ListInitiatives', 'ReadInitiative'];
+/** The note and initiative tools that change something. */
+export const EXTENSION_NOTE_WRITE_TOOLS = [
+    'CreateNote',
+    'EditNote',
+    'PatchNote',
+    'RenameNote',
+    'DeleteNote',
+    'CreateInitiative',
+    'MoveNotesToInitiative',
+    'MarkInitiativeComplete',
+    'EditInitiativeArtifacts',
+    'EditInitiativeGroups',
+];
 /** Every method name the bridge accepts, so Odyn can refuse anything else. */
 export const EXTENSION_API_METHODS = [
     'chats.list',
@@ -73,6 +139,15 @@ export const EXTENSION_API_METHODS = [
     'fetch',
     'showToast',
     'preferences',
+    'ui.openDialog',
+    'ui.setBadge',
+    'ui.setChatChip',
+    'dashboard.setCard',
+    'storage.get',
+    'storage.set',
+    'storage.keys',
+    'notes.run',
+    'notes.get',
 ];
 function buildOdynApi(bridge) {
     const call = (method, ...args) => bridge.call(method, args);
@@ -87,6 +162,23 @@ function buildOdynApi(bridge) {
         fetch: (url, init) => call('fetch', url, init ?? null),
         showToast: (message) => call('showToast', message),
         preferences: () => call('preferences'),
+        ui: {
+            openDialog: (options) => call('ui.openDialog', options ?? null),
+            setBadge: (count) => call('ui.setBadge', count),
+            setChatChip: (chatId, chip) => call('ui.setChatChip', chatId, chip),
+        },
+        dashboard: { setCard: (card) => call('dashboard.setCard', card) },
+        storage: {
+            get: (key) => call('storage.get', key),
+            set: (key, value) => call('storage.set', key, value),
+            keys: (prefix) => call('storage.keys', prefix ?? ''),
+        },
+        notes: {
+            run: (tool, target, input) => call('notes.run', tool, target, input),
+            list: (projectId) => call('notes.get', 'list', projectId),
+            initiative: (projectId, initiativeId) => call('notes.get', 'initiative', projectId, initiativeId),
+            read: (projectId, noteId) => call('notes.get', 'note', projectId, noteId),
+        },
     };
 }
 function errorText(error) {
@@ -119,6 +211,47 @@ const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** A GitHub username: letters, digits and single dashes, up to 39 characters. */
 const GITHUB_USERNAME_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
 const ENTRY_PATTERN = /^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+\.html$/;
+/** The most pictures a manifest's `screenshots` may list. */
+export const MAX_EXTENSION_SCREENSHOTS = 5;
+/** The biggest a single screenshot file may be: 1 MB. */
+export const MAX_EXTENSION_SCREENSHOT_BYTES = 1024 * 1024;
+/** The picture types a screenshot may be (compared ignoring capitals). */
+export const EXTENSION_SCREENSHOT_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp'];
+/** What is wrong with one screenshot path, or null when it is fine. */
+function screenshotPathProblem(path) {
+    if (typeof path !== 'string' || path.trim() === '')
+        return 'Every screenshot must be a path to a file.';
+    const label = `Screenshot "${path}"`;
+    // A colon catches both web addresses ("https:") and Windows drives ("C:").
+    if (path.includes(':'))
+        return `${label} must be a path inside the extension's folder, not a web address or drive.`;
+    if (path.includes('\\'))
+        return `${label} must use forward slashes (/).`;
+    if (path.startsWith('/'))
+        return `${label} must be a path inside the extension's folder, not one starting with "/".`;
+    if (path.split('/').includes('..'))
+        return `${label} must not step outside the extension's folder with "..".`;
+    const lower = path.toLowerCase();
+    if (!EXTENSION_SCREENSHOT_EXTENSIONS.some((ending) => lower.endsWith(ending))) {
+        return `${label} must be a ${EXTENSION_SCREENSHOT_EXTENSIONS.join(', ')} file.`;
+    }
+    return null;
+}
+function screenshotProblems(screenshots) {
+    if (screenshots === undefined)
+        return [];
+    if (!Array.isArray(screenshots))
+        return ['`screenshots` must be a list of file paths.'];
+    const problems = [];
+    if (screenshots.length > MAX_EXTENSION_SCREENSHOTS)
+        problems.push(`\`screenshots\` can list at most ${MAX_EXTENSION_SCREENSHOTS} pictures.`);
+    for (const path of screenshots) {
+        const problem = screenshotPathProblem(path);
+        if (problem)
+            problems.push(problem);
+    }
+    return problems;
+}
 function surfaceProblems(surfaces, apiVersion) {
     if (surfaces.length === 0)
         return [];
@@ -148,11 +281,151 @@ function surfaceProblems(surfaces, apiVersion) {
     if (surfaces.filter((surface) => surface.placement === 'composer').length > 1)
         problems.push('Only one page can sit in the message box.');
     if (surfaces.filter((surface) => surface.placement === 'settings').length > 1)
-        problems.push('Only one page can sit in the settings window.');
+        problems.push('An extension can have only one settings page.');
+    if (surfaces.filter((surface) => surface.placement === 'dialog').length > 1)
+        problems.push('Only one page can fill the dialog.');
+    if (apiVersion < 5 && surfaces.some((surface) => surface.placement === 'dialog'))
+        problems.push('A dialog page needs `apiVersion` 5.');
     if (apiVersion < 3 && surfaces.some((surface) => surface.placement === 'settings'))
         problems.push('A settings page needs `apiVersion` 3.');
     return problems;
 }
+/** Checks the sidebar button, the dashboard card and the `ui:` permissions (kit version 5). */
+function uiProblems(manifest, apiVersion) {
+    const problems = [];
+    const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : [];
+    const commandNames = Array.isArray(manifest.commands) ? manifest.commands.map((command) => command?.name) : [];
+    const asksUi = permissions.some((permission) => permission === 'ui:sidebar' || permission === 'ui:dialog' || permission === 'ui:dashboard');
+    if (apiVersion < 5 && asksUi)
+        problems.push('The `ui:` permissions need `apiVersion` 5.');
+    const asksNotes = permissions.some((permission) => permission === 'notes:read' || permission === 'notes:write');
+    if (apiVersion < 6 && asksNotes)
+        problems.push('The `notes:` permissions need `apiVersion` 6.');
+    const item = manifest.sidebarItem;
+    if (item !== undefined) {
+        if (apiVersion < 5)
+            problems.push('`sidebarItem` needs `apiVersion` 5.');
+        if (!permissions.includes('ui:sidebar'))
+            problems.push('`sidebarItem` needs the `ui:sidebar` permission.');
+        if (typeof item !== 'object' || item === null)
+            problems.push('`sidebarItem` must be an object.');
+        else {
+            if (typeof item.title !== 'string' || item.title.trim() === '' || item.title.length > DASHBOARD_CARD_MAX_TITLE)
+                problems.push('`sidebarItem` needs a short title.');
+            if (!EXTENSION_SURFACE_ICONS.includes(item.icon))
+                problems.push('`sidebarItem` has an unknown icon.');
+            if (!commandNames.includes(item.command))
+                problems.push('`sidebarItem.command` must name one of the `commands`.');
+        }
+    }
+    const menuItem = manifest.composerMenuItem;
+    if (menuItem !== undefined) {
+        if (apiVersion < 6)
+            problems.push('`composerMenuItem` needs `apiVersion` 6.');
+        if (!permissions.includes('ui:dialog'))
+            problems.push('`composerMenuItem` needs the `ui:dialog` permission.');
+        if (typeof menuItem !== 'object' || menuItem === null)
+            problems.push('`composerMenuItem` must be an object.');
+        else {
+            if (typeof menuItem.title !== 'string' || menuItem.title.trim() === '' || menuItem.title.length > DASHBOARD_CARD_MAX_TITLE)
+                problems.push('`composerMenuItem` needs a short title.');
+            if (!EXTENSION_SURFACE_ICONS.includes(menuItem.icon))
+                problems.push('`composerMenuItem` has an unknown icon.');
+            if (!commandNames.includes(menuItem.command))
+                problems.push('`composerMenuItem.command` must name one of the `commands`.');
+        }
+    }
+    const card = manifest.dashboardCard;
+    if (card !== undefined) {
+        if (apiVersion < 5)
+            problems.push('`dashboardCard` needs `apiVersion` 5.');
+        if (!permissions.includes('ui:dashboard'))
+            problems.push('`dashboardCard` needs the `ui:dashboard` permission.');
+        if (typeof card !== 'object' || card === null || !commandNames.includes(card.command))
+            problems.push('`dashboardCard.command` must name one of the `commands`.');
+    }
+    const chip = manifest.chatChip;
+    if (chip !== undefined) {
+        if (apiVersion < 6)
+            problems.push('`chatChip` needs `apiVersion` 6.');
+        if (!permissions.includes('ui:chatHeader'))
+            problems.push('`chatChip` needs the `ui:chatHeader` permission.');
+        if (typeof chip !== 'object' || chip === null || !commandNames.includes(chip.command))
+            problems.push('`chatChip.command` must name one of the `commands`.');
+    }
+    else if (permissions.includes('ui:chatHeader')) {
+        problems.push('`ui:chatHeader` needs a `chatChip`.');
+    }
+    const surfaces = Array.isArray(manifest.surfaces) ? manifest.surfaces : [];
+    if (surfaces.some((surface) => surface?.placement === 'dialog') && !permissions.includes('ui:dialog'))
+        problems.push('A dialog page needs the `ui:dialog` permission.');
+    return problems;
+}
+function isShortText(value, max) {
+    return typeof value === 'string' && value.trim() !== '' && value.length <= max;
+}
+/** Why a dashboard card can't be drawn. An empty list means it is fine. */
+export function dashboardCardProblems(value) {
+    if (typeof value !== 'object' || value === null)
+        return ['The card is not an object.'];
+    const card = value;
+    const problems = [];
+    if (!isShortText(card.title, DASHBOARD_CARD_MAX_TITLE))
+        problems.push(`The card needs a title of up to ${DASHBOARD_CARD_MAX_TITLE} characters.`);
+    if (!Array.isArray(card.items) || card.items.length > DASHBOARD_CARD_MAX_ITEMS)
+        problems.push(`\`items\` must be a list of up to ${DASHBOARD_CARD_MAX_ITEMS}.`);
+    else {
+        const ids = new Set();
+        for (const item of card.items) {
+            if (typeof item !== 'object' || item === null || !isShortText(item.id, DASHBOARD_CARD_MAX_TITLE) || ids.has(item.id ?? ''))
+                problems.push('Every item needs its own `id`.');
+            else
+                ids.add(item.id ?? '');
+            if (!isShortText(item?.title, DASHBOARD_CARD_MAX_TITLE))
+                problems.push(`Every item needs a title of up to ${DASHBOARD_CARD_MAX_TITLE} characters.`);
+            if (item?.subtitle !== undefined && !isShortText(item.subtitle, DASHBOARD_CARD_MAX_SUBTITLE))
+                problems.push(`An item's subtitle can be up to ${DASHBOARD_CARD_MAX_SUBTITLE} characters.`);
+        }
+    }
+    if (card.actions !== undefined) {
+        if (!Array.isArray(card.actions) || card.actions.length > DASHBOARD_CARD_MAX_ACTIONS)
+            problems.push(`\`actions\` must be a list of up to ${DASHBOARD_CARD_MAX_ACTIONS}.`);
+        else {
+            const ids = new Set();
+            for (const action of card.actions) {
+                if (typeof action !== 'object' || action === null || !isShortText(action.id, DASHBOARD_CARD_MAX_TITLE) || ids.has(action.id ?? ''))
+                    problems.push('Every action needs its own `id`.');
+                else
+                    ids.add(action.id ?? '');
+                if (!isShortText(action?.title, DASHBOARD_CARD_MAX_TITLE))
+                    problems.push(`Every action needs a title of up to ${DASHBOARD_CARD_MAX_TITLE} characters.`);
+                if (action?.opensDialog !== undefined && typeof action.opensDialog !== 'boolean')
+                    problems.push('`opensDialog` must be true or false.');
+            }
+        }
+    }
+    return problems;
+}
+/**
+ * Whether an agent tool's `card` answer can be shown in the chat as a card
+ * the person answers (kit version 6). It is a dashboard card with one or two
+ * buttons; a click runs the same tool again with the button's `actionId`.
+ * Use it to ask before doing something, e.g. "This looks like part of X —
+ * [Not now] [Link chat]". A card that fails these checks reaches the agent
+ * as plain text, as before.
+ */
+export function chatCardProblems(value) {
+    const problems = [...dashboardCardProblems(value)];
+    if (problems.length > 0)
+        return problems;
+    const actions = value.actions ?? [];
+    if (actions.length === 0)
+        problems.push('A chat card needs at least one button in `actions`.');
+    if (actions.some((action) => action.opensDialog !== undefined)) {
+        problems.push('Chat card buttons cannot use `opensDialog` — call `odyn.ui.openDialog()` from the command instead.');
+    }
+    return problems;
+}
 const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const SCRIPT_PATTERN = /^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+\.js$/;
 const FOLDER_PATTERN = /^(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/;
@@ -203,6 +476,9 @@ function helperProblems(manifest, apiVersion) {
     if (helper.downloadHosts !== undefined && (!Array.isArray(helper.downloadHosts) || helper.downloadHosts.some((host) => typeof host !== 'string' || !/^[a-z0-9.-]+$/.test(host)))) {
         problems.push('`helper.downloadHosts` must be a list of host names.');
     }
+    if (helper.browserSafeCalls !== undefined && (!Array.isArray(helper.browserSafeCalls) || helper.browserSafeCalls.some((name) => typeof name !== 'string' || !NAME_PATTERN.test(name)))) {
+        problems.push('`helper.browserSafeCalls` must be a list of call names.');
+    }
     return problems;
 }
 function agentProblems(manifest, apiVersion) {
@@ -307,12 +583,13 @@ export function validateManifest(value, options = {}) {
             problems.push(`\`platforms\` must list some of: ${EXTENSION_PLATFORMS.join(', ')}.`);
         }
     }
-    problems.push(...helperProblems(manifest, apiVersion), ...agentProblems(manifest, apiVersion));
+    problems.push(...helperProblems(manifest, apiVersion), ...agentProblems(manifest, apiVersion), ...uiProblems(manifest, apiVersion));
     if (manifest.owners !== undefined) {
         if (!Array.isArray(manifest.owners) || manifest.owners.some((owner) => typeof owner !== 'string' || !GITHUB_USERNAME_PATTERN.test(owner))) {
             problems.push('`owners` must be a list of GitHub usernames.');
         }
     }
+    problems.push(...screenshotProblems(manifest.screenshots));
     const hasSurfaces = Array.isArray(surfaces) && surfaces.length > 0;
     const hasHelper = manifest.helper !== undefined;
     // From version 4 a guide for the agent is enough on its own.
@@ -335,9 +612,24 @@ export function validateManifest(value, options = {}) {
                 problems.push(`Agent tool "${command.name}" needs a description.`);
             problems.push(...inputProblems(command, apiVersion));
         }
+        problems.push(...contextProblems(manifest, apiVersion));
     }
     return problems;
 }
+function contextProblems(manifest, apiVersion) {
+    const contextCommands = (manifest.commands ?? []).filter((command) => command?.placement === 'chatContext');
+    const asksContext = Array.isArray(manifest.permissions) && manifest.permissions.includes('agent:context');
+    if (contextCommands.length === 0)
+        return asksContext ? ['`agent:context` needs a `chatContext` command.'] : [];
+    const problems = [];
+    if (apiVersion < 6)
+        problems.push('A `chatContext` command needs `apiVersion` 6.');
+    if (!asksContext)
+        problems.push('A `chatContext` command needs the `agent:context` permission.');
+    if (contextCommands.length > 1)
+        problems.push('An extension can have only one `chatContext` command.');
+    return problems;
+}
 // --- An extension's own page (kit version 2) -----------------------------
 //
 // The page runs in a sealed box inside Odyn's window. It talks to Odyn only by
@@ -346,10 +638,27 @@ export function validateManifest(value, options = {}) {
 /** Every message between a page and Odyn carries this tag. */
 export const SURFACE_MESSAGE_TAG = 'odyn-surface';
 /** Every call a page can make, so Odyn can refuse anything else. */
-export const EXTENSION_SURFACE_METHODS = ['chatStorage.get', 'chatStorage.set', 'composer.attachImage', 'helper.call'];
+export const EXTENSION_SURFACE_METHODS = [
+    'chatStorage.get',
+    'chatStorage.set',
+    'composer.attachImage',
+    'helper.call',
+    'storage.get',
+    'storage.set',
+    'storage.keys',
+    'notes.run',
+    'notes.get',
+    'chats.list',
+    'projects.list',
+    'ui.setChatChip',
+];
 /** The most a page may keep for one chat, and the largest picture it may attach. */
 export const SURFACE_STORAGE_MAX_BYTES = 5_000_000;
+/** The most an extension may keep in its shared `storage` altogether. */
+export const EXTENSION_STORAGE_MAX_BYTES = 50_000_000;
 export const SURFACE_IMAGE_MAX_BYTES = 10_000_000;
+/** The longest `item` a dialog can be opened at. */
+export const DIALOG_ITEM_MAX_LENGTH = 200;
 export function isSurfaceMessage(value) {
     return typeof value === 'object' && value !== null && value.tag === SURFACE_MESSAGE_TAG;
 }
@@ -412,6 +721,20 @@ export function connectSurface() {
             get: (chatId, key) => call('chatStorage.get', chatId, key),
             set: (chatId, key, value) => call('chatStorage.set', chatId, key, value),
         },
+        storage: {
+            get: (key) => call('storage.get', key),
+            set: (key, value) => call('storage.set', key, value),
+            keys: (prefix) => call('storage.keys', prefix ?? ''),
+        },
+        notes: {
+            run: (tool, target, input) => call('notes.run', tool, target, input),
+            list: (projectId) => call('notes.get', 'list', projectId),
+            initiative: (projectId, initiativeId) => call('notes.get', 'initiative', projectId, initiativeId),
+            read: (projectId, noteId) => call('notes.get', 'note', projectId, noteId),
+        },
+        chats: { list: (projectId) => call('chats.list', projectId ?? null) },
+        projects: { list: () => call('projects.list') },
+        ui: { setChatChip: (chatId, chip) => call('ui.setChatChip', chatId, chip) },
         composer: {
             attachImage: (image) => call('composer.attachImage', image),
             close: () => post({ tag: SURFACE_MESSAGE_TAG, kind: 'close' }),
@@ -448,6 +771,8 @@ export const EXTENSION_HELPER_METHODS = [
     'sessions.set',
     'sessions.frame',
     'pages.post',
+    'ui.setBadge',
+    'dashboard.setCard',
 ];
 /** The events Odyn sends a helper. */
 export const EXTENSION_HELPER_EVENTS = ['watch', 'unwatch', 'input', 'close', 'agentCommand', 'chatClosed', 'shutdown', 'pageCall'];
@@ -483,6 +808,10 @@ export function defineHelper(definition) {
             },
             post: (message) => call('pages.post', message),
         },
+        ui: { setBadge: (count) => call('ui.setBadge', count) },
+        dashboard: {
+            setCard: (card) => call('dashboard.setCard', card),
+        },
     };
     const settle = (replyId, work) => {
         Promise.resolve()
@@ -564,6 +893,11 @@ export function starterFiles(options) {
             '```',
             '',
             'In Odyn, open Marketplace → Extensions → Install from folder and pick this folder.',
+            '',
+            'Optional: add up to 5 pictures to the Marketplace page by listing them in the',
+            '`"odyn"` section of package.json, e.g. `"screenshots": ["screenshots/1.png"]`',
+            '(.png, .jpg, .jpeg or .webp, at most 1 MB each).',
+            '',
             'Docs: https://www.odyn.build/docs/extensions',
             '',
         ].join('\n'),

package/dist/ui/button.d.ts

@@ -3,7 +3,7 @@ import { type VariantProps } from 'class-variance-authority';
 /** The Odyn button styles, for use on other elements too. */
 export declare const buttonVariants: (props?: ({
     variant?: "default" | "destructive" | "link" | "outline" | "secondary" | "ghost" | null | undefined;
-    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+    size?: "default" | "icon" | "xs" | "sm" | "lg" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ButtonProps = ComponentProps<'button'> & VariantProps<typeof buttonVariants>;
 /** A button in Odyn's style. Icon-only buttons need an `aria-label`. */

package/dist/ui/orb/orb-frame-clock.d.ts

@@ -16,7 +16,15 @@ export declare const ORB_FRAMES_PER_SECOND = 12;
 export declare const ORB_ROOT_ATTRIBUTE = "data-orb";
 /** Present on an orb held on its opening frame; the clock leaves those alone. */
 export declare const ORB_PAUSED_ATTRIBUTE = "data-orb-paused";
-/** Moves every clocked animation to where it should be at `now`. */
+/**
+ * Moves every clocked animation to where it should be at `now`.
+ *
+ * Reads first, then writes. Asking a CSS animation for its `playState` makes
+ * the browser bring every style on the page up to date, and setting
+ * `currentTime` makes them stale again. Mixing the two in one loop paid for a
+ * whole-page style pass per animation, per tick — the main cause of lag when
+ * switching chats. Splitting them means at most one style pass per tick.
+ */
 export declare function tickOrbClock(now: number): void;
 /**
  * Hands these animations to the shared clock, carrying on from wherever each

package/dist/ui/orb/orb-frame-clock.js

@@ -31,17 +31,28 @@ function stopClockIfIdle() {
     clearInterval(clockTimer);
     clockTimer = null;
 }
-/** Moves every clocked animation to where it should be at `now`. */
+/**
+ * Moves every clocked animation to where it should be at `now`.
+ *
+ * Reads first, then writes. Asking a CSS animation for its `playState` makes
+ * the browser bring every style on the page up to date, and setting
+ * `currentTime` makes them stale again. Mixing the two in one loop paid for a
+ * whole-page style pass per animation, per tick — the main cause of lag when
+ * switching chats. Splitting them means at most one style pass per tick.
+ */
 export function tickOrbClock(now) {
-    for (const [animation, origin] of clockedAnimations) {
-        // The stylesheet removed it (the orb left the page, or reduce-motion was
-        // switched on), so stop driving it — setting its time would revive it.
-        if (animation.playState === 'idle') {
-            clockedAnimations.delete(animation);
-            continue;
-        }
+    // Read every animation's state BEFORE moving any of them. Reading
+    // `playState` makes the browser bring the whole page's styles up to date,
+    // and moving an animation makes them stale again — so reading and moving
+    // in turn redid the whole page's styles once per dot, about 200 times a
+    // second, which grew with the page until a long chat froze the window.
+    const stale = [...clockedAnimations.keys()].filter((animation) => animation.playState === 'idle');
+    // The stylesheet removed these (the orb left the page, or reduce-motion was
+    // switched on), so stop driving them — setting their time would revive them.
+    for (const animation of stale)
+        clockedAnimations.delete(animation);
+    for (const [animation, origin] of clockedAnimations)
         animation.currentTime = now - origin;
-    }
     stopClockIfIdle();
 }
 function tickWhenVisible() {
@@ -56,10 +67,12 @@ function tickWhenVisible() {
  * one already is. Handing over one that is already clocked does nothing.
  */
 export function clockOrbAnimations(animations, now = performance.now()) {
-    for (const animation of animations) {
-        if (animation.playState === 'idle' || clockedAnimations.has(animation))
-            continue;
-        clockedAnimations.set(animation, now - readCurrentTime(animation));
+    // Reads first, then writes — see `tickOrbClock` for why.
+    const fresh = animations
+        .filter((animation) => !clockedAnimations.has(animation) && animation.playState !== 'idle')
+        .map((animation) => [animation, now - readCurrentTime(animation)]);
+    for (const [animation, origin] of fresh) {
+        clockedAnimations.set(animation, origin);
         animation.pause();
     }
     if (clockedAnimations.size > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odyn-app/api",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The public building kit for Odyn extensions.",
   "license": "MIT",
   "homepage": "https://github.com/New-Genre/odyn-extensions",