@odyn-app/api 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @odyn-app/api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The building kit for [Odyn](https://github.com/New-Genre/odyn-extensions) extensions.
+
+```bash
+bun add @odyn-app/api
+```
+
+```ts
+import { defineExtension } from '@odyn-app/api'
+
+defineExtension({
+  commands: {
+    'say-hello': async () => ({ type: 'detail', markdown: 'Hello from my extension.' }),
+  },
+})
+```
+
+- `@odyn-app/api`: `defineExtension`, the `odyn` bridge, the manifest types and the manifest checker.
+- `@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.
+
+Every extension runs sandboxed, and each call is checked against the permissions the user granted. To make one and publish it to Odyn's Marketplace, see the [contribution guide](https://github.com/New-Genre/odyn-extensions/blob/main/CONTRIBUTING.md).
+
+MIT licence.

package/dist/index.d.ts

@@ -0,0 +1,492 @@
+/** The newest building-kit version. Bumped when something new is added. */
+export declare const EXTENSION_API_VERSION = 4;
+/** 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 type ExtensionPermission = (typeof EXTENSION_PERMISSIONS)[number];
+/** Permissions only extensions made by Odyn may ask for. */
+export declare const OFFICIAL_ONLY_PERMISSIONS: readonly ExtensionPermission[];
+/** 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"];
+export type ExtensionPlacement = (typeof EXTENSION_PLACEMENTS)[number];
+export interface ExtensionCommand {
+    /** Unique within the extension, e.g. "show-standup". */
+    readonly name: string;
+    readonly title: string;
+    readonly placement: ExtensionPlacement;
+    /** For `agentTool`: what the agent is told the tool does. */
+    readonly description?: string;
+    /** For `agentTool`: what the agent fills in when it calls the tool. Needs `apiVersion` 4. */
+    readonly inputs?: readonly ExtensionCommandInput[];
+}
+/** The kinds of value an agent tool's input can take. */
+export declare const EXTENSION_INPUT_TYPES: readonly ["string", "number", "boolean"];
+export type ExtensionInputType = (typeof EXTENSION_INPUT_TYPES)[number];
+/** One thing the agent fills in when it calls an agent tool. */
+export interface ExtensionCommandInput {
+    /** Letters, digits and underscores, starting with a letter, e.g. "city". */
+    readonly name: string;
+    /** What the agent is told to put here. */
+    readonly description: string;
+    readonly type: ExtensionInputType;
+    readonly required?: boolean;
+}
+/** 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 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];
+export declare const SURFACE_MIN_HEIGHT = 120;
+export declare const SURFACE_MAX_HEIGHT = 600;
+/**
+ * The extension's own page. Odyn shows it in a sealed box: no internet, no
+ * access to Odyn beyond `connectSurface()`, and no way out of its box.
+ */
+export interface ExtensionSurface {
+    /** Unique within the extension, e.g. "canvas". */
+    readonly id: string;
+    readonly title: string;
+    /**
+     * `composer`: slides open above the message box, with a toolbar button.
+     * `settings`: shown inside the extension's settings window.
+     */
+    readonly placement: ExtensionSurfacePlacement;
+    /** The page inside the extension's folder, e.g. "dist/panel/index.html". */
+    readonly entry: string;
+    readonly icon?: ExtensionSurfaceIcon;
+    /** Height in pixels. Defaults to 260. */
+    readonly height?: number;
+}
+export interface ExtensionPreference {
+    readonly name: string;
+    readonly title: string;
+    readonly type: 'text' | 'password' | 'checkbox';
+    readonly required?: boolean;
+}
+/**
+ * A Mac program a helper may run. Odyn looks in `locations` in order and uses
+ * the first that exists. A location may start with `~`, `$DATA` (the
+ * extension's own data folder), `$USER_DATA` (Odyn's), or an environment
+ * variable such as `$ANDROID_HOME`; a bare name is looked up on PATH.
+ */
+export interface ExtensionProgram {
+    /** Unique within the extension, e.g. "adb". */
+    readonly name: string;
+    readonly locations: readonly string[];
+    /** Put this program's folder on the agent's PATH while the extension is on. */
+    readonly exposeToAgent?: boolean;
+}
+/** A folder a helper may look up (never read or write), found like a program. */
+export interface ExtensionFolder {
+    readonly name: string;
+    readonly locations: readonly string[];
+}
+/** The official-only background helper. Needs `programs:run` and `apiVersion` 3. */
+export interface ExtensionHelper {
+    /** The built helper script, e.g. "dist/helper.js". */
+    readonly entry: string;
+    readonly programs: readonly ExtensionProgram[];
+    readonly folders?: readonly ExtensionFolder[];
+    /** Exact links the helper may open, e.g. an App Store page. */
+    readonly links?: readonly string[];
+    /** Hosts `download` may fetch from (redirects must stay inside the list). */
+    readonly downloadHosts?: readonly string[];
+}
+/** A command the agent must ask before using, e.g. `{ program: 'xcrun', subcommand: 'simctl' }`. */
+export interface ExtensionGatedCommand {
+    readonly program: string;
+    readonly subcommand?: string;
+}
+/**
+ * What the extension gives the agent. Needs `agent:tools` and `apiVersion` 3.
+ * From version 4 the guide is optional: an extension may give only tools.
+ */
+export interface ExtensionAgent {
+    /** The guide's name, which is also what the user types, e.g. "odyn-phone" → `/odyn-phone`. */
+    readonly skill?: string;
+    /** The folder holding the guide's SKILL.md, e.g. "skill". */
+    readonly skillFolder?: string;
+    /** One sentence telling the agent what this gives it. */
+    readonly summary: string;
+    /** Commands that need the user's OK in a chat first. */
+    readonly gatedCommands?: readonly ExtensionGatedCommand[];
+    /** What the agent wants to do, for the one-click card, e.g. "use a phone". */
+    readonly accessLabel?: string;
+}
+export interface ExtensionManifest {
+    /** Unique store id, lowercase with dashes, e.g. "standup-notes". */
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly author: string;
+    readonly version: string;
+    /** The building-kit version this was built against. */
+    readonly apiVersion: number;
+    readonly permissions: readonly ExtensionPermission[];
+    /** Hosts `fetch` may reach. Required when `network` is asked for. */
+    readonly allowedHosts?: readonly string[];
+    readonly commands: readonly ExtensionCommand[];
+    /** Its own pages. Needs `apiVersion` 2. */
+    readonly surfaces?: readonly ExtensionSurface[];
+    readonly preferences?: readonly ExtensionPreference[];
+    /** Systems it runs on; hidden elsewhere. Needs `apiVersion` 3. */
+    readonly platforms?: readonly ExtensionPlatform[];
+    /** Background helper. Official extensions only. */
+    readonly helper?: ExtensionHelper;
+    /** A guide and permission-checked commands for the agent. */
+    readonly agent?: ExtensionAgent;
+}
+export interface ExtensionAction {
+    readonly id: string;
+    readonly title: string;
+    readonly style?: 'default' | 'destructive';
+}
+export interface ListItem {
+    readonly id: string;
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly accessory?: string;
+    readonly actions?: readonly ExtensionAction[];
+}
+export type ExtensionView = {
+    readonly type: 'list';
+    readonly items: readonly ListItem[];
+    readonly emptyText?: string;
+} | {
+    readonly type: 'detail';
+    readonly markdown: string;
+    readonly actions?: readonly ExtensionAction[];
+} | {
+    readonly type: 'form';
+    readonly fields: readonly {
+        readonly name: string;
+        readonly title: string;
+        readonly type: 'text' | 'textarea' | 'checkbox';
+    }[];
+    readonly submitTitle: string;
+};
+export interface ChatSummary {
+    readonly id: string;
+    readonly projectId: string;
+    readonly title: string;
+    readonly updatedAt: string;
+}
+export interface ProjectSummary {
+    readonly id: string;
+    readonly name: string;
+}
+export interface ChatMessageSummary {
+    readonly role: 'user' | 'assistant' | 'system';
+    readonly content: string;
+    readonly createdAt: string;
+}
+/** Odyn's side of the conversation. Every call is permission-checked by Odyn. */
+export interface OdynApi {
+    readonly chats: {
+        list(projectId?: string): Promise<readonly ChatSummary[]>;
+        messages(chatId: string, limit?: number): Promise<readonly ChatMessageSummary[]>;
+        /** The chat the user is looking at, if any. */
+        current(): Promise<ChatSummary | null>;
+    };
+    readonly projects: {
+        list(): Promise<readonly ProjectSummary[]>;
+    };
+    readonly agents: {
+        /** Sends a prompt to a chat, starting the agent there. */
+        start(chatId: string, prompt: string): Promise<void>;
+    };
+    /** `fetch`, limited to the manifest's `allowedHosts`. */
+    fetch(url: string, init?: {
+        readonly method?: string;
+        readonly headers?: Record<string, string>;
+        readonly body?: string;
+    }): Promise<{
+        readonly status: number;
+        readonly text: string;
+    }>;
+    showToast(message: string): Promise<void>;
+    /** The values the user saved in the extension's settings. */
+    preferences(): Promise<Readonly<Record<string, string | boolean>>>;
+}
+/** 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. */
+    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>>;
+}
+/** Draws a view, or (for an agent tool) returns text for the agent. */
+export type CommandHandler = (context: CommandContext) => Promise<ExtensionView | string | void>;
+export interface ExtensionDefinition {
+    readonly commands: Readonly<Record<string, CommandHandler>>;
+}
+/** A command run Odyn asks the extension to do. */
+export interface ExtensionRunRequest {
+    readonly callId: string;
+    readonly command: string;
+    readonly actionId?: string;
+    readonly itemId?: string;
+    readonly input?: Readonly<Record<string, ExtensionInputValue>>;
+}
+export type ExtensionRunResult = {
+    readonly ok: true;
+    readonly value: ExtensionView | string | null;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** The bridge Odyn's loader places on the page before an extension runs. */
+export interface ExtensionBridge {
+    call(method: string, args: readonly unknown[]): Promise<unknown>;
+    onRun(listener: (request: ExtensionRunRequest) => void): void;
+    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 type ExtensionApiMethod = (typeof EXTENSION_API_METHODS)[number];
+/**
+ * The one call an extension's entry file makes. Inside Odyn it hooks the
+ * commands up to Odyn; anywhere else (tests, the store checker) it just
+ * hands the definition back.
+ */
+export declare function defineExtension(definition: ExtensionDefinition): ExtensionDefinition;
+/** Returns every problem with a manifest; an empty list means it is fine. */
+export interface ManifestCheckOptions {
+    /**
+     * Made by Odyn and shipped inside the app. An official extension may be
+     * nothing but an on/off switch for a feature built into Odyn, so it doesn't
+     * need a command, page, helper or agent section.
+     */
+    readonly official?: boolean;
+}
+export declare function validateManifest(value: unknown, options?: ManifestCheckOptions): readonly string[];
+/** 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 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;
+export declare const SURFACE_IMAGE_MAX_BYTES = 10000000;
+/** What the page is showing for. Sent on open and whenever it changes. */
+export interface SurfaceContext {
+    readonly chatId: string | null;
+    readonly theme: 'light' | 'dark';
+}
+/** A picture handed over by Odyn (a screenshot) or attached by the page. */
+export interface SurfaceImage {
+    readonly name: string;
+    readonly mimeType: string;
+    readonly bytes: Uint8Array;
+}
+/** Messages a page sends to Odyn. */
+export type SurfaceOutgoingMessage = {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: 'ready';
+} | {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: 'close';
+} | {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: 'call';
+    readonly id: string;
+    readonly method: ExtensionSurfaceMethod;
+    readonly args: readonly unknown[];
+};
+/** Messages Odyn sends to a page. */
+export type SurfaceIncomingMessage = {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: 'context';
+    readonly context: SurfaceContext;
+} | {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: 'image';
+    readonly image: SurfaceImage;
+} | {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: 'helperMessage';
+    readonly message: unknown;
+} | {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: 'result';
+    readonly id: string;
+    readonly ok: boolean;
+    readonly value?: unknown;
+    readonly error?: string;
+};
+/** What a page can do. Get it with `connectSurface()`. */
+export interface OdynSurfaceApi {
+    /** Called straight away with the current chat and theme, then on every change. */
+    onContext(listener: (context: SurfaceContext) => void): () => void;
+    /** Called when the user hands the page a screenshot. Needs `screenshots:read`. */
+    onImage(listener: (image: SurfaceImage) => void): () => void;
+    /** A small text store per chat, deleted with the chat or when the extension is switched off. */
+    readonly chatStorage: {
+        get(chatId: string, key: string): Promise<string | null>;
+        /** `null` removes the value. */
+        set(chatId: string, key: string, value: string | null): Promise<void>;
+    };
+    readonly composer: {
+        /** Puts a picture onto the user's message. Needs `composer:attach`. */
+        attachImage(image: SurfaceImage): Promise<void>;
+        /** Closes the page. */
+        close(): void;
+    };
+    /** The extension's own helper, when it has one. */
+    readonly helper: {
+        /** Asks the helper to do something it registered with `odyn.pages.handle`. */
+        call<T = unknown>(name: string, ...args: readonly unknown[]): Promise<T>;
+        /** Called when the helper posts to the extension's open pages. */
+        onMessage(listener: (message: unknown) => void): () => void;
+    };
+}
+export declare function isSurfaceMessage(value: unknown): value is {
+    readonly tag: typeof SURFACE_MESSAGE_TAG;
+    readonly kind: string;
+};
+/** The one call a page makes to start talking to Odyn. */
+export declare function connectSurface(): OdynSurfaceApi;
+/** Devices Odyn knows how to draw a live screen for. */
+export declare const SCREEN_SESSION_DEVICES: readonly ["iphone", "android"];
+export type ScreenSessionDevice = (typeof SCREEN_SESSION_DEVICES)[number];
+/** A live screen the helper shows in the sidebar, tied to the chat it belongs to. */
+export interface ScreenSession {
+    /** Unique within the extension. */
+    readonly id: string;
+    readonly chatId: string;
+    readonly title: string;
+    readonly device: ScreenSessionDevice;
+}
+/** Taps and swipes arrive as fractions of the screen (0 to 1). */
+export type ScreenInput = {
+    readonly kind: 'tap';
+    readonly x: number;
+    readonly y: number;
+} | {
+    readonly kind: 'swipe';
+    readonly fromX: number;
+    readonly fromY: number;
+    readonly toX: number;
+    readonly toY: number;
+} | {
+    readonly kind: 'type';
+    readonly text: string;
+} | {
+    readonly kind: 'home';
+} | {
+    readonly kind: 'button';
+    readonly button: 'power' | 'volume-up' | 'volume-down';
+};
+export interface ProgramRunOptions {
+    /** Extra environment variables. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Milliseconds. Defaults to 15 seconds; at most an hour. */
+    readonly timeoutMs?: number;
+    /** Written to the program's input once, repeated `stdinRepeat` times (for licence prompts). */
+    readonly stdin?: string;
+    readonly stdinRepeat?: number;
+    /** Return what the program prints as bytes instead of text. */
+    readonly binary?: boolean;
+    /**
+     * Odyn makes a scratch file, puts its path wherever an argument is
+     * `$OUTPUT_FILE`, and hands the file's bytes back as `file`.
+     */
+    readonly outputFile?: boolean;
+}
+export interface ProgramResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    /** The last part of what the program printed as errors. */
+    readonly stderr: string;
+    /** Set with `binary` (what it printed) or `outputFile` (the file's bytes). */
+    readonly bytes?: Uint8Array;
+}
+/** What a helper can ask Odyn to do. */
+export interface OdynHelperApi {
+    readonly programs: {
+        /** Where a listed program is, or null when none of its locations exist. */
+        find(name: string): Promise<string | null>;
+        /** Runs a listed program and waits for it. Arguments may use `$DATA` for the data folder. */
+        run(name: string, args: readonly string[], options?: ProgramRunOptions): Promise<ProgramResult>;
+        /** Starts a listed program in the background and does not wait. */
+        launch(name: string, args: readonly string[], options?: {
+            readonly env?: Readonly<Record<string, string>>;
+        }): Promise<void>;
+    };
+    readonly folders: {
+        /** Where a listed folder is, or null. */
+        find(name: string): Promise<string | null>;
+    };
+    /** The extension's own data folder: kept across updates, deleted on uninstall. */
+    readonly data: {
+        path(): Promise<string>;
+        /** Downloads into the data folder, checking an `sha512-…` integrity value when given. */
+        download(url: string, relativePath: string, integrity?: string): Promise<void>;
+        remove(relativePath: string): Promise<void>;
+        makeFolder(relativePath: string): Promise<void>;
+    };
+    /** Opens one of the manifest's `helper.links`. */
+    openLink(url: string): Promise<void>;
+    showToast(message: string): Promise<void>;
+    readonly sessions: {
+        /** Replaces the whole list of live screens. */
+        set(sessions: readonly ScreenSession[]): Promise<void>;
+        /** Sends a new picture of a screen that someone is watching. */
+        frame(sessionId: string, bytes: Uint8Array, mimeType: 'image/png' | 'image/jpeg'): Promise<void>;
+    };
+    readonly pages: {
+        /** Answers `helper.call(name, …)` from the extension's pages. */
+        handle(name: string, handler: (...args: readonly unknown[]) => Promise<unknown> | unknown): void;
+        /** Sends a message to every open page of this extension. */
+        post(message: unknown): Promise<void>;
+    };
+}
+/** Things that happen, delivered to the helper. */
+export interface HelperEvents {
+    /** Someone opened a live screen; send frames until `unwatch`. */
+    watch?(sessionId: string): void;
+    unwatch?(sessionId: string): void;
+    input?(sessionId: string, input: ScreenInput): Promise<void> | void;
+    /** The user pressed Close on a live screen. */
+    close?(sessionId: string): Promise<void> | void;
+    /** The agent ran a shell command using one of the extension's gated commands. */
+    agentCommand?(chatId: string, command: string): void;
+    /** A chat was archived or deleted. */
+    chatClosed?(chatId: string): Promise<void> | void;
+    /** The extension is being switched off or Odyn is quitting. Clean up quickly. */
+    shutdown?(): Promise<void> | void;
+}
+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 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"];
+export type ExtensionHelperEvent = (typeof EXTENSION_HELPER_EVENTS)[number];
+/** A helper's answer to an event that waits for one (input, close, page calls). */
+export type HelperReply = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** The bridge Odyn's loader places on a helper's page. */
+export interface HelperBridge {
+    call(method: ExtensionHelperMethod, args: readonly unknown[]): Promise<unknown>;
+    onEvent(listener: (event: ExtensionHelperEvent, args: readonly unknown[], replyId: string | null) => void): void;
+    reply(replyId: string, result: HelperReply): void;
+}
+/** The one call a helper's script makes. Anywhere but Odyn it just hands the definition back. */
+export declare function defineHelper(definition: HelperDefinition): HelperDefinition;