@holokai/harbor-sdk 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+import type { App } from '@modelcontextprotocol/ext-apps';
+import { type BarInput, type BarSetParams, type BarSetResult, type BrowserOpenParams, type BrowserOpenResult, type CapabilitiesListResult, type FilesAddParams, type FilesAddResult, type FilesLinkParams, type FilesOpenParams, type FilesOpenResult, type HarborEventMap, type HarborEventName, type HarborViewNames, type HarborViewState, type HarborMethod, type ViewsOpenParams, type ViewsOpenResult, type ViewStatusParams, type ViewStatusResult, type WorkflowsGetResult, type WorkflowsListParams, type WorkflowsListResult, type WorkflowsSubmitParams, type WorkflowsSubmitResult } from './contract';
+export type * from './contract';
+export type * from './page-reader';
+export { BAR_LIMITS, HARBOR_EXTENSION_ID, HARBOR_EXTENSION_VERSION, HARBOR_METHODS, HARBOR_PAGE_READER, HARBOR_VIEW_NAME_LIMITS, HARBOR_VIEW_NAMES_ID, HARBOR_VIEW_STATE_LIMITS, MCP_APPS_PROTOCOL_VERSION, VIEW_STATUSES, } from './contract';
+/** What a listener hears when a delivery was lost: re-read a snapshot. */
+export interface HarborEventGap {
+    subscriptionId: string;
+    expected: number;
+    received: number;
+}
+export interface HarborEventOptions {
+    /** A `seq` was skipped — an event was lost. Events are invalidation signals; there is no replay. */
+    onGap?: (gap: HarborEventGap) => void;
+}
+export interface HarborConnection {
+    /** The extension version harbor advertised. Methods are additive within a major. */
+    readonly version: string;
+    /** What THIS view is granted — feature-detect per method and event. */
+    readonly granted: {
+        readonly methods: readonly HarborMethod[];
+        readonly events: readonly HarborEventName[];
+    };
+    readonly workflows: {
+        list(params?: WorkflowsListParams): Promise<WorkflowsListResult>;
+        /** Submit a DAG to BigBrain and start it. Its events arrive on `workflow.task` / `workflow.changed`. */
+        submit(params: WorkflowsSubmitParams): Promise<WorkflowsSubmitResult>;
+        /** Read a workflow this app submitted — the tasks, their states and outputs. */
+        get(workflowId: string): Promise<WorkflowsGetResult>;
+    };
+    readonly capabilities: {
+        /** What a DAG may name: harbor's built-ins, Holo apps, this app's own tools, other connectors'. */
+        list(): Promise<CapabilitiesListResult>;
+    };
+    readonly files: {
+        /** Ask harbor to open a file: it calls `tool` on this app's server for the bytes and opens a read-only copy. */
+        open(params: FilesOpenParams): Promise<FilesOpenResult>;
+        /** Ask harbor to add a file to the workspace this page was opened to pick for, through `tool` as `open` does. */
+        add(params: FilesAddParams): Promise<FilesAddResult>;
+        /** Ask harbor to link a folder or a file to the workspace this page was opened to pick for; its chats read it in place. */
+        link(params: FilesLinkParams): Promise<FilesAddResult>;
+    };
+    readonly browser: {
+        /** Ask harbor to open an https URL in the person's own browser. Anything else is refused. */
+        open(params: BrowserOpenParams): Promise<BrowserOpenResult>;
+    };
+    readonly bar: {
+        /** Hand harbor's window bar this page's search field and account menu. Replaces the whole bar. */
+        set(params: BarSetParams): Promise<BarSetResult>;
+        /** Hear what the person types or chooses in the bar, and the trail step they press. Returns the unsubscribe. */
+        on(handler: (input: BarInput) => void): () => void;
+    };
+    readonly views: {
+        /**
+         * Open this same page again in a new window beside this one, booted with
+         * `view` as its saved view and called `title` until it names what it shows.
+         */
+        open(params: ViewsOpenParams): Promise<ViewsOpenResult>;
+        /**
+         * Set what this page's tray button shows about the work behind it. The
+         * button is the extension's, so every view of it shares the status.
+         */
+        status(params: ViewStatusParams): Promise<ViewStatusResult>;
+    };
+    readonly events: {
+        /** Subscribe to one event. Returns the unsubscribe. */
+        on<K extends HarborEventName>(name: K, listener: (payload: HarborEventMap[K]) => void, options?: HarborEventOptions): () => void;
+    };
+}
+/**
+ * One report of what a view is showing: text for the model, the structured
+ * view for the host, the names of what is open, or any of them. ALWAYS the
+ * whole picture — the host slot is last-write-wins, so a field left out is a
+ * field erased.
+ */
+export interface HarborViewSnapshot {
+    /** A sentence for the model: what this page is showing, in words. */
+    text?: string;
+    /** The structured view — harbor's to remember and hand back on the next boot. */
+    state?: HarborViewState;
+    /** The names of what is open and where it sits, for the host's own sentence. */
+    names?: HarborViewNames;
+}
+/**
+ * The view harbor saved for this page, handed back with the handshake.
+ * `null` under any host that saved nothing, and under every host but harbor.
+ * Call AFTER `app.connect()`.
+ */
+export declare function savedView(app: App): HarborViewState | null;
+/**
+ * Tell the host what this page is showing. Works under ANY MCP Apps host, and
+ * sends each half only where the host advertised that modality: a host with no
+ * `structuredContent` marker gets the text block and NEITHER harbor key, so a
+ * pane width and a subject line never enter a foreign model's context.
+ *
+ * A snapshot with nothing the host takes sends nothing at all.
+ */
+export declare function reportView(app: App, snapshot: HarborViewSnapshot): Promise<void>;
+/**
+ * Connect to harbor's extension, or learn that this host is not harbor.
+ * Call AFTER `app.connect()` — the host's capabilities arrive with the
+ * handshake. Idempotent per `App`: the same connection comes back.
+ */
+export declare function connectHarbor(app: App): HarborConnection | null;

package/dist/index.js

@@ -0,0 +1,212 @@
+import {createRequire as __harborCreateRequire} from 'node:module'; const require = __harborCreateRequire(import.meta.url);
+import {
+  BAR_LIMITS,
+  HARBOR_BAR_NOTIFICATION,
+  HARBOR_EVENT_NOTIFICATION,
+  HARBOR_EXTENSION_ID,
+  HARBOR_EXTENSION_VERSION,
+  HARBOR_METHODS,
+  HARBOR_PAGE_READER,
+  HARBOR_VIEW_NAMES_ID,
+  HARBOR_VIEW_NAME_LIMITS,
+  HARBOR_VIEW_STATE_LIMITS,
+  MCP_APPS_PROTOCOL_VERSION,
+  VIEW_STATUSES
+} from "./chunks/chunk-G4KJ2OCU.js";
+
+// src/index.ts
+var passThrough = () => ({
+  "~standard": { version: 1, vendor: "harbor-sdk", validate: (value) => ({ value }) }
+});
+function savedView(app) {
+  const carried = app.getHostContext()?.[HARBOR_EXTENSION_ID];
+  if (typeof carried !== "object" || carried === null) return null;
+  const state = carried.viewState;
+  return typeof state === "object" && state !== null ? state : null;
+}
+async function reportView(app, snapshot) {
+  const modalities = app.getHostCapabilities()?.updateModelContext;
+  const structured = modalities?.structuredContent !== void 0;
+  const text = modalities?.text !== void 0 && snapshot.text !== void 0 ? snapshot.text : void 0;
+  const state = structured && snapshot.state !== void 0 ? snapshot.state : void 0;
+  const names = structured && snapshot.names !== void 0 ? snapshot.names : void 0;
+  if (text === void 0 && state === void 0 && names === void 0) return;
+  await app.updateModelContext({
+    ...text === void 0 ? {} : { content: [{ type: "text", text }] },
+    ...state === void 0 && names === void 0 ? {} : {
+      structuredContent: {
+        ...state === void 0 ? {} : { [HARBOR_EXTENSION_ID]: state },
+        ...names === void 0 ? {} : { [HARBOR_VIEW_NAMES_ID]: names }
+      }
+    }
+  });
+}
+var connections = /* @__PURE__ */ new WeakMap();
+function connectHarbor(app) {
+  if (connections.has(app)) return connections.get(app) ?? null;
+  const extension = readExtension(app.getHostCapabilities()?.experimental?.[HARBOR_EXTENSION_ID]);
+  const connection = extension ? new Connection(app, extension) : null;
+  connections.set(app, connection);
+  return connection;
+}
+function readExtension(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const record = value;
+  if (typeof record["version"] !== "string") return null;
+  const methods = Array.isArray(record["methods"]) ? record["methods"].filter((m) => typeof m === "string") : [];
+  const events = Array.isArray(record["events"]) ? record["events"].filter((e) => typeof e === "string") : [];
+  return { version: record["version"], methods, events };
+}
+var Connection = class {
+  version;
+  granted;
+  workflows;
+  capabilities;
+  files;
+  browser;
+  bar;
+  views;
+  events;
+  #app;
+  #listeners = /* @__PURE__ */ new Set();
+  #barHandlers = /* @__PURE__ */ new Set();
+  #subscription = null;
+  /**
+   * A notification MAY arrive before the subscribe result that names its
+   * subscriptionId — main pushes on one channel and answers on another,
+   * and nothing orders the two. So the handler is registered ONCE, before
+   * any subscribe is sent, and holds what it cannot yet place until the
+   * result lands.
+   */
+  #held = [];
+  #resync = Promise.resolve();
+  constructor(app, extension) {
+    this.#app = app;
+    this.version = extension.version;
+    this.granted = { methods: [...extension.methods], events: [...extension.events] };
+    this.workflows = {
+      list: (params = {}) => this.#request(HARBOR_METHODS.workflowsList, { ...params }),
+      submit: (params) => this.#request(HARBOR_METHODS.workflowsSubmit, { ...params }),
+      get: (workflowId) => this.#request(HARBOR_METHODS.workflowsGet, { workflowId })
+    };
+    this.capabilities = {
+      list: () => this.#request(HARBOR_METHODS.capabilitiesList, {})
+    };
+    this.files = {
+      open: (params) => this.#request(HARBOR_METHODS.filesOpen, { ...params }),
+      add: (params) => this.#request(HARBOR_METHODS.filesAdd, { ...params }),
+      link: (params) => this.#request(HARBOR_METHODS.filesLink, { ...params })
+    };
+    this.browser = {
+      open: (params) => this.#request(HARBOR_METHODS.browserOpen, { ...params })
+    };
+    this.bar = {
+      set: (params) => this.#request(HARBOR_METHODS.barSet, { ...params }),
+      on: (handler) => {
+        this.#barHandlers.add(handler);
+        return () => {
+          this.#barHandlers.delete(handler);
+        };
+      }
+    };
+    this.views = {
+      open: (params) => this.#request(HARBOR_METHODS.viewsOpen, { ...params }),
+      status: (params) => this.#request(HARBOR_METHODS.viewStatus, { ...params })
+    };
+    this.events = { on: (name, listener, options) => this.#on(name, listener, options) };
+    app.setNotificationHandler(HARBOR_BAR_NOTIFICATION, { params: passThrough() }, (input) => {
+      for (const handler of this.#barHandlers) handler(input);
+    });
+    app.setNotificationHandler(
+      HARBOR_EVENT_NOTIFICATION,
+      { params: passThrough() },
+      (params) => this.#onEvent(params)
+    );
+  }
+  #request(method, params) {
+    return this.#app.request({ method, params }, passThrough());
+  }
+  #on(event, fn, options) {
+    const listener = {
+      event,
+      fn,
+      ...options?.onGap ? { onGap: options.onGap } : {}
+    };
+    this.#listeners.add(listener);
+    this.#queueResync();
+    return () => {
+      this.#listeners.delete(listener);
+      this.#queueResync();
+    };
+  }
+  /** Serialized: one subscribe/unsubscribe in flight at a time, in call order. */
+  #queueResync() {
+    this.#resync = this.#resync.then(() => this.#resyncSubscription()).catch(() => void 0);
+  }
+  async #resyncSubscription() {
+    const wanted = /* @__PURE__ */ new Set();
+    for (const listener of this.#listeners) wanted.add(listener.event);
+    const current = this.#subscription;
+    const same = current !== null && current.events.size === wanted.size && [...wanted].every((e) => current.events.has(e));
+    if (same) return;
+    if (wanted.size === 0) {
+      this.#subscription = null;
+      if (current) await this.#unsubscribe(current.id);
+      return;
+    }
+    const result = await this.#request(HARBOR_METHODS.eventsSubscribe, {
+      events: [...wanted]
+    });
+    this.#subscription = { id: result.subscriptionId, events: new Set(result.events), seq: 0 };
+    this.#flushHeld();
+    if (current) await this.#unsubscribe(current.id);
+  }
+  async #unsubscribe(subscriptionId) {
+    try {
+      await this.#request(HARBOR_METHODS.eventsUnsubscribe, { subscriptionId });
+    } catch {
+    }
+  }
+  #onEvent(params) {
+    const subscription = this.#subscription;
+    if (subscription === null || params.subscriptionId !== subscription.id) {
+      this.#held.push(params);
+      return;
+    }
+    this.#dispatch(subscription, params);
+  }
+  #flushHeld() {
+    const subscription = this.#subscription;
+    const held = this.#held;
+    this.#held = [];
+    if (subscription === null) return;
+    for (const params of held.filter((p) => p.subscriptionId === subscription.id).sort((a, b) => a.seq - b.seq)) {
+      this.#dispatch(subscription, params);
+    }
+  }
+  #dispatch(subscription, params) {
+    const expected = subscription.seq + 1;
+    if (params.seq < expected) return;
+    const gap = params.seq > expected ? { subscriptionId: subscription.id, expected, received: params.seq } : null;
+    subscription.seq = params.seq;
+    for (const listener of this.#listeners) {
+      if (gap && listener.onGap) listener.onGap(gap);
+      if (listener.event === params.event) listener.fn(params.payload);
+    }
+  }
+};
+export {
+  BAR_LIMITS,
+  HARBOR_EXTENSION_ID,
+  HARBOR_EXTENSION_VERSION,
+  HARBOR_METHODS,
+  HARBOR_PAGE_READER,
+  HARBOR_VIEW_NAMES_ID,
+  HARBOR_VIEW_NAME_LIMITS,
+  HARBOR_VIEW_STATE_LIMITS,
+  MCP_APPS_PROTOCOL_VERSION,
+  VIEW_STATUSES,
+  connectHarbor,
+  reportView,
+  savedView
+};

package/dist/manifest.d.ts

@@ -0,0 +1,26 @@
+/** The manifest type a first-party extension exports and harbor reads. */
+import type { DeclaredGrant } from './contract';
+/** An image for an extension, the MCP `Icon` shape; `src` is a data: URL. */
+export interface ExtensionIcon {
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+}
+/** Who an extension is: what harbor shows for it and what it needs to run. */
+export interface ExtensionManifest {
+    /** The path segment it is served at, lowercase letters, digits and dashes, starting with a letter. */
+    name: string;
+    title: string;
+    description: string;
+    version: string;
+    /**
+     * The name of the sign-in provider it signs in through, such as `microsoft`. Extensions that share one
+     * run in one process, a connection, so they share one sign-in.
+     */
+    provider: string;
+    icon?: ExtensionIcon;
+    /** The names of the settings it reads from its environment, such as `MICROSOFT_CLIENT_ID`. */
+    settings: readonly string[];
+    /** The grants harbor gives only to an extension that names them, such as `files.add`. */
+    grants?: readonly DeclaredGrant[];
+}

package/dist/manifest.js

@@ -0,0 +1 @@
+import {createRequire as __harborCreateRequire} from 'node:module'; const require = __harborCreateRequire(import.meta.url);

package/dist/package.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The package contract: what makes an npm package an extension Harbor can run, and the installed catalog a tree carries.
+ * It imports nothing at run time, so Harbor's main process, the extension host and the build scripts all read it.
+ */
+import type { ExtensionManifest } from './manifest';
+/** The extension-to-host API version. A host runs only extensions that declare it. */
+export declare const EXTENSION_API_VERSION = 1;
+/** Packages a tree holds exactly once: host-provided contracts and shared sign-in state. */
+export declare const SINGLETON_PACKAGES: readonly ["@holokai/harbor-sdk", "@holokai/harbor-kit", "@holokai/harbor-google", "@holokai/harbor-microsoft", "@holokai/harbor-atlassian", "@holokai/harbor-relay"];
+/** The `harbor` field of a published package's package.json: which kind of package it is. */
+export type HarborPackageField = {
+    type: 'extension';
+    apiVersion: number;
+} | {
+    type: 'library';
+};
+/** The package.json fields Harbor reads. */
+export interface ExtensionPackageMetadata {
+    name: string;
+    version: string;
+    harbor: HarborPackageField;
+}
+/** One extension in an installed tree. Paths are relative to the folder holding catalog.json. */
+export interface InstalledCatalogEntry {
+    /** The manifest's name, which is also the extension's folder name. */
+    name: string;
+    package: string;
+    version: string;
+    apiVersion: number;
+    manifest: ExtensionManifest;
+    /** `node_modules/<package>/dist/main.js` */
+    entry: string;
+    /** `pages/<name>/app.html` */
+    page: string;
+}
+/** `tree/catalog.json`: what one installed tree holds. */
+export interface InstalledCatalog {
+    apiVersion: number;
+    /** The SDK version installed in this tree. */
+    sdkVersion: string;
+    /** The release set the tree was made from, or `local` for a tree packed from the workspace. */
+    releaseSet: string;
+    extensions: InstalledCatalogEntry[];
+}
+/** Why one entry of a catalog does not load. */
+export interface CatalogSkip {
+    name: string;
+    package: string;
+    reason: 'api_version' | 'manifest' | 'shape';
+}
+/** The catalog file's name inside a tree. */
+export declare const CATALOG_FILE = "catalog.json";
+/** A manifest, or null when a field is missing or of the wrong type. Only ExtensionManifest's fields survive. */
+export declare function parseExtensionManifest(value: unknown): ExtensionManifest | null;
+/**
+ * The entries a host may run, and the ones it must skip. Null when the value is not an installed catalog at all.
+ * A repeated name, or an entry or page path that leaves the catalog's folder, is skipped as `shape`.
+ */
+export declare function parseInstalledCatalog(value: unknown): {
+    catalog: InstalledCatalog;
+    skipped: CatalogSkip[];
+} | null;
+/** The installed catalog's entry path for a package, relative to the tree. */
+export declare const entryPathOf: (packageName: string) => string;
+/** The installed catalog's page path for an extension, relative to the tree. */
+export declare const pagePathOf: (name: string) => string;
+/**
+ * The one writer of catalog.json: from each installed extension package's package.json and dist/manifest.json, sorted
+ * by name. Throws on a package that is not an extension or a manifest that does not parse, so a broken tree is never
+ * written.
+ */
+export declare function catalogFor(input: {
+    releaseSet: string;
+    sdkVersion: string;
+    packages: readonly {
+        metadata: ExtensionPackageMetadata;
+        manifest: unknown;
+    }[];
+}): InstalledCatalog;

package/dist/package.js

@@ -0,0 +1,131 @@
+import {createRequire as __harborCreateRequire} from 'node:module'; const require = __harborCreateRequire(import.meta.url);
+
+// src/package.ts
+var EXTENSION_API_VERSION = 1;
+var SINGLETON_PACKAGES = [
+  "@holokai/harbor-sdk",
+  "@holokai/harbor-kit",
+  "@holokai/harbor-google",
+  "@holokai/harbor-microsoft",
+  "@holokai/harbor-atlassian",
+  "@holokai/harbor-relay"
+];
+var CATALOG_FILE = "catalog.json";
+var NAME = /^[a-z][a-z0-9-]*$/;
+var VERSION_CORE = /^\d+\.\d+\.\d+$/;
+var PRERELEASE = /^[0-9A-Za-z.-]+$/;
+function isVersion(value) {
+  const dash = value.indexOf("-");
+  if (dash === -1) return VERSION_CORE.test(value);
+  return VERSION_CORE.test(value.slice(0, dash)) && PRERELEASE.test(value.slice(dash + 1));
+}
+var DECLARED_GRANTS = /* @__PURE__ */ new Set(["files.add"]);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isString = (value) => typeof value === "string";
+var isStringArray = (value) => Array.isArray(value) && value.every(isString);
+function parseIcon(value) {
+  if (!isRecord(value) || !isString(value.src) || !value.src.startsWith("data:")) return null;
+  if (value.mimeType !== void 0 && !isString(value.mimeType)) return null;
+  if (value.sizes !== void 0 && !isStringArray(value.sizes)) return null;
+  return {
+    src: value.src,
+    ...value.mimeType === void 0 ? {} : { mimeType: value.mimeType },
+    ...value.sizes === void 0 ? {} : { sizes: [...value.sizes] }
+  };
+}
+function parseExtensionManifest(value) {
+  if (!isRecord(value)) return null;
+  const { name, title, description, version, provider, icon, settings, grants } = value;
+  if (!isString(name) || !NAME.test(name)) return null;
+  if (!isString(title) || !isString(description) || !isString(provider) || !NAME.test(provider)) return null;
+  if (!isString(version) || !isVersion(version)) return null;
+  if (!isStringArray(settings)) return null;
+  const parsedIcon = icon === void 0 ? void 0 : parseIcon(icon);
+  if (parsedIcon === null) return null;
+  if (grants !== void 0 && !(isStringArray(grants) && grants.every((grant) => DECLARED_GRANTS.has(grant)))) {
+    return null;
+  }
+  return {
+    name,
+    title,
+    description,
+    version,
+    provider,
+    ...parsedIcon === void 0 ? {} : { icon: parsedIcon },
+    settings: [...settings],
+    ...grants === void 0 ? {} : { grants: [...grants] }
+  };
+}
+function staysInside(relative) {
+  return relative.length > 0 && !relative.startsWith("/") && !relative.includes("\\") && !/^[A-Za-z]:/.test(relative) && relative.split("/").every((segment) => segment !== ".." && segment !== "");
+}
+function parseInstalledCatalog(value) {
+  if (!isRecord(value) || !Array.isArray(value.extensions)) return null;
+  const { apiVersion, sdkVersion, releaseSet } = value;
+  if (typeof apiVersion !== "number" || !isString(sdkVersion) || !isString(releaseSet)) return null;
+  const extensions = [];
+  const skipped = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of value.extensions) {
+    const name = isRecord(raw) && isString(raw.name) ? raw.name : "";
+    const packageName = isRecord(raw) && isString(raw.package) ? raw.package : "";
+    const skip = (reason) => skipped.push({ name, package: packageName, reason });
+    if (!isRecord(raw) || !NAME.test(name) || packageName === "" || seen.has(name) || !isString(raw.version) || !isString(raw.entry) || !isString(raw.page) || !staysInside(raw.entry) || !staysInside(raw.page)) {
+      skip("shape");
+      continue;
+    }
+    seen.add(name);
+    if (raw.apiVersion !== EXTENSION_API_VERSION) {
+      skip("api_version");
+      continue;
+    }
+    const manifest = parseExtensionManifest(raw.manifest);
+    if (manifest === null || manifest.name !== name || manifest.version !== raw.version) {
+      skip("manifest");
+      continue;
+    }
+    extensions.push({
+      name,
+      package: packageName,
+      version: raw.version,
+      apiVersion: raw.apiVersion,
+      manifest,
+      entry: raw.entry,
+      page: raw.page
+    });
+  }
+  return { catalog: { apiVersion, sdkVersion, releaseSet, extensions }, skipped };
+}
+var entryPathOf = (packageName) => `node_modules/${packageName}/dist/main.js`;
+var pagePathOf = (name) => `pages/${name}/app.html`;
+function catalogFor(input) {
+  const extensions = input.packages.map(({ metadata, manifest: raw }) => {
+    if (metadata.harbor.type !== "extension") throw new Error(`${metadata.name} is not an extension package`);
+    const manifest = parseExtensionManifest(raw);
+    if (manifest === null) throw new Error(`${metadata.name}: its dist/manifest.json is not a manifest`);
+    if (manifest.version !== metadata.version) {
+      throw new Error(`${metadata.name}: its manifest says ${manifest.version}, its package ${metadata.version}`);
+    }
+    return {
+      name: manifest.name,
+      package: metadata.name,
+      version: metadata.version,
+      apiVersion: metadata.harbor.apiVersion,
+      manifest,
+      entry: entryPathOf(metadata.name),
+      page: pagePathOf(manifest.name)
+    };
+  });
+  extensions.sort((a, b) => a.name.localeCompare(b.name));
+  return { apiVersion: EXTENSION_API_VERSION, sdkVersion: input.sdkVersion, releaseSet: input.releaseSet, extensions };
+}
+export {
+  CATALOG_FILE,
+  EXTENSION_API_VERSION,
+  SINGLETON_PACKAGES,
+  catalogFor,
+  entryPathOf,
+  pagePathOf,
+  parseExtensionManifest,
+  parseInstalledCatalog
+};

package/dist/page-reader.d.ts

@@ -0,0 +1,53 @@
+import type { HarborViewState } from './contract';
+/**
+ * The page reader: one AI tool per extension, `read_page`, that takes a
+ * page's own reported location and answers what is there. Its answer reaches
+ * the model as that tool's result, never as pasted context. Harbor finds it
+ * by the mark `_meta['ai.holokai/harbor'].reads === 'page'`.
+ */
+/** A location on a page, as it reports its view: the place, item and filter ids and the search text, never names. */
+export type PageAt = Pick<HarborViewState, 'place' | 'item' | 'filter' | 'query'>;
+/**
+ * A place the page can go, with its name and how many items it holds. A
+ * hierarchy is a flat list in order, each place's `depth` below the top (0 when
+ * absent), because a recursive schema does not survive Harbor's tool catalog.
+ */
+export interface PagePlace {
+    at: PageAt;
+    name: string;
+    count?: number;
+    depth?: number;
+}
+/** One item worth opening from here, with where it is. */
+export interface PageTarget {
+    at: PageAt;
+    name: string;
+}
+/** What the page reader answers: what is at the location, as text and as the extension's own data. */
+export interface PageRead<D> {
+    /** The location read, with its name. */
+    shows: {
+        at: PageAt;
+        name: string;
+    };
+    /** What the model reads, sent as the tool's content; the other fields are its structured content. */
+    text: string;
+    data: D;
+    /** Where the page can go from here. */
+    places: PagePlace[];
+    /** Items worth opening from here. */
+    targets: PageTarget[];
+}
+/** Harbor's own entries in a tool's `_meta['ai.holokai/harbor']`. */
+export interface HarborToolMeta {
+    /** The tool that opens the extension's page. */
+    entry?: true;
+    /** The tool that reads what the page shows. */
+    reads?: 'page';
+    /**
+     * On a page-only tool: the AI tool whose calls it describes for the Allow Once question. It takes
+     * that tool's input and answers what the call would do, without doing it. Harbor reads it only
+     * from a first-party extension.
+     */
+    previews?: string;
+}