Metabot Metaapp

Bot MetaApp

Use this as the single MetaApp workflow entrypoint. A MetaApp is a browser-runnable HTML application package, usually a ZIP-backed static app, recorded on chain through /protocols/metaapp. A Bot homepage is a special MetaApp use case when the app is designed for a Bot's public metaid:// page.

Routing

Route natural-language intent through $HOME/.metabot/bin/metabot, then reason over the returned JSON envelope.

• Prefer JSON and local daemon routes for agent workflows.
• Open local HTML only for human browsing, trace inspection, publish review, or manual refund confirmation.
• Treat MetaWeb as the network layer and the local host as a thin adapter.

Actor Selection

Separate read targets from write actors.

• Use a target globalMetaId only to read Bot Homepage data or build links to a Bot.
• Use --from for uploads, MetaApp publish/update/delete, share announcements, comments, and Bot homepage pointer writes.
• Do not infer that the target Bot and local publishing Bot are the same unless the human says so.
• Confirm the MetaBot actor before every on-chain write.
• Before upload batches or final on-chain writes, state the MetaBot actor, chain, and files or payload being written.
• Do not omit --from unless the human explicitly confirms that the active identity is the intended owner.

Commands that write chain data require explicit confirmation through the command contract, usually --confirm.

Intent Routing

Classify the request first.

1. Existing static site, frontend project, or ZIP -> use the Publish Wizard.
2. New app with Agent Internet links or Browser capabilities -> use MetaApp Development Rules, then the Publish Wizard.
3. Bot homepage or Bot Page -> use Bot Homepage MetaApp Rules, then the Publish Wizard, then optionally set /info/homepage.
4. Existing MetaApp management -> use Direct CLI Shortcuts.

Do not use this skill for raw hosting, unrelated file upload, paid skill service publishing, identity creation, network source management, wallet transfer, or private chat.

MetaApp Development Rules

Build a static, browser-runnable app. It may be a pure HTML app, but prefer Agent Internet resource links for ecosystem resources.

Use these URI schemes for Agent Internet resources:

metaid://
pin://
pin://?version=
metaapp://
metafile://
map:///pin/
map:///pin/?version=
map://simplemsg/conversation?peer=

Use https:// only for normal external web pages, not for MetaID resources that already have an Agent Internet URI.

For assets that ship inside the MetaApp package, use relative URLs only.

• Good: assets/figures/diagram.png, ./assets/figures/diagram.png, ../shared/app.css
• Bad: /assets/figures/diagram.png, /css/app.css, /js/app.js

A leading / resolves against the Browser host root, not the mounted MetaApp package. MetaApps open under routes such as /browser/metaapp/, so root-absolute packaged asset URLs 404 even when the files exist inside the ZIP. Apply this rule to HTML, CSS url(...), Markdown-rendered images, and client-side fetches for packaged JSON or media.

If an asset is not packaged locally, use a full https://... URL or an explicit Agent Internet URI such as metafile://... when the runtime supports it. Do not use site-root absolute paths as a shortcut.

When the app renders remote image fields, resolve MetaFile references to a browser-fetchable image URL before assigning them to ` unless the host runtime explicitly documents native metafile://` image support.

Keep MetaFile image resolution configurable:

• If the system already provides metafileContentBaseUrl or manApiBaseUrl, treat those configured values as authoritative.
• The public URLs below are fallback bases only. Do not hard-code them over system settings.
• Use the generic MetaFile fallback base https://file.metaid.io/metafile-indexer/api/v1/files/accelerate/content for normal metafile://... image content.
• Use the avatar fallback base https://file.metaid.io/metafile-indexer/content for Bot or profile avatar pins when no system manApiBaseUrl is available.

Use this resolution order for remote image fields such as Bot homepage avatars, MetaApp icons, covers, gallery images, or section thumbnails:

1. If the value is already data:, blob:, or http(s):, use it as-is.
2. If the value is metafile://[.], a bare pin id, or a known content path, extract the pin id first.
3. If the image is an avatar and the system provides manApiBaseUrl, build /content/.
4. Otherwise, if the system provides a dedicated MetaFile image base, use that configured base.
5. Otherwise, fall back to https://file.metaid.io/metafile-indexer/content/ for avatars or https://file.metaid.io/metafile-indexer/api/v1/files/accelerate/content/ for other MetaFile-backed images.

Example helper:

  function normalizeText(value) {
    return typeof value === 'string' ? value.trim() : '';
  }

  function extractMetafilePinId(value) {
    var raw = normalizeText(value);
    if (!raw) return '';
    if (/^https?:\/\//i.test(raw)) {
      try {
        raw = new URL(raw).pathname || '';
      } catch {
        return '';
      }
    } else if (/^metafile:\/\//i.test(raw)) {
      raw = raw.slice('metafile://'.length);
    }
    raw = decodeURIComponent((raw.split(/[?#]/, 1)[0] || '').replace(/^\/+/, ''));
    raw = raw
      .replace(/^content\//i, '')
      .replace(/^metafile-indexer\/content\//i, '')
      .replace(/^metafile-indexer\/thumbnail\//i, '')
      .replace(/^metafile-indexer\/api\/v1\/files\/content\//i, '')
      .replace(/^metafile-indexer\/api\/v1\/files\/accelerate\/content\//i, '')
      .replace(/^metafile-indexer\/api\/v1\/users\/avatar\/accelerate\//i, '');
    var match = raw.match(/^([0-9a-f]{64}i0)(?:\.[a-z0-9][a-z0-9+.-]{0,31})?$/i);
    return match && match[1] ? match[1] : '';
  }

  function trimTrailingSlash(value) {
    return normalizeText(value).replace(/\/+$/, '');
  }

  function resolveMetaFileImageUrl(reference, options) {
    var raw = normalizeText(reference);
    if (!raw) return '';
    if (/^(data:|blob:|https?:)/i.test(raw)) return raw;
    var pinId = extractMetafilePinId(raw);
    if (!pinId) return '';
    var config = options || {};
    var fallbackMetafileBase = 'https://file.metaid.io/metafile-indexer/api/v1/files/accelerate/content';
    var fallbackAvatarBase = 'https://file.metaid.io/metafile-indexer/content';
    if (config.kind === 'avatar') {
      var avatarBase = trimTrailingSlash(config.manApiBaseUrl);
      return (avatarBase ? avatarBase + '/content' : fallbackAvatarBase) + '/' + encodeURIComponent(pinId);
    }
    var metafileBase = trimTrailingSlash(config.metafileContentBaseUrl) || fallbackMetafileBase;
    return metafileBase + '/' + encodeURIComponent(pinId);
  }

Static anchors are valid:

Open Bot
Open PIN
Open MetaApp

Inside a custom MetaApp iframe, add an AgentBrowser helper once near the end of body so Agent Internet links navigate through Agent Browser:

  (function () {
    var callbacks = {};
    var listeners = {};
    var nextId = 1;
    var bridge = window.AgentBrowser || {};

    bridge.navigate = bridge.navigate || function (uri) {
      window.parent.postMessage({
        type: 'agent-browser:navigate',
        version: 1,
        uri: String(uri || '')
      }, '*');
    };

    bridge.request = bridge.request || function (input) {
      var id = 'req-' + (nextId++);
      return new Promise(function (resolve, reject) {
        callbacks[id] = { resolve: resolve, reject: reject };
        window.parent.postMessage({
          type: 'agent-browser:request',
          version: 1,
          id: id,
          method: String(input && input.method || ''),
          params: input && input.params || {}
        }, '*');
      });
    };

    bridge.on = bridge.on || function (eventName, handler) {
      if (!listeners[eventName]) listeners[eventName] = [];
      listeners[eventName].push(handler);
      return function () {
        listeners[eventName] = (listeners[eventName] || []).filter(function (item) {
          return item !== handler;
        });
      };
    };

    window.addEventListener('message', function (event) {
      var data = event && event.data || {};
      if (data.type === 'agent-browser:response' && callbacks[data.id]) {
        var callback = callbacks[data.id];
        delete callbacks[data.id];
        if (data.ok) callback.resolve(data.result);
        else {
          var error = new Error(data.error && data.error.message || 'AgentBrowser request failed');
          error.code = data.error && data.error.code || 'bridge_error';
          callback.reject(error);
        }
      }
      if (data.type === 'agent-browser:event') {
        (listeners[data.event] || []).forEach(function (handler) {
          handler(data.payload);
        });
      }
    });

    window.AgentBrowser = bridge;
  }());

  document.addEventListener('click', function (event) {
    var link = event.target && event.target.closest ? event.target.closest('a[href]') : null;
    if (!link) return;
    var href = link.getAttribute('href') || '';
    if (!/^(metaid|pin|metaapp|metafile|map):\/\//i.test(href)) return;
    event.preventDefault();
    window.AgentBrowser.navigate(href);
  });

Use window.AgentBrowser.request only for host-mediated Browser capabilities:

• browser.actor.current to read the selected actor snapshot.
• metaid.pin.write for create, modify, or revoke of MetaID PIN records.
• metafile.upload before writing app records that reference files.

Do not request wallet APIs, private keys, payment APIs, host routes, local file paths, parent DOM access, or Web2 avatar access from inside the MetaApp.

Bot Homepage MetaApp Rules

Use these rules when the user wants a Bot Page, Bot homepage, personal Bot profile, Bot portfolio, or Bot share page.

Require:

• globalMetaId: the target Bot Global MetaID used for homepage data.

Optional:

• botSlug: local Bot slug used for publish and homepage pointer writes.
• projectDir: static homepage project directory.
• targetPinId: existing MetaApp pin id for update.
• Visual direction: pass this to the frontend-capable builder.

Fetch v3 homepage data from:

https://so.metaid.io/api/bot-homepage/globalmetaid/?version=v3

The HTTP response is an envelope. Require body.code === 0 and body.data.schemaVersion === "botHomepage.v3" before treating it as valid v3 data.

The generated project must include data.json as a local snapshot of the API response. Use hybrid loading:

1. Render from data.json first.
2. Attempt to fetch the v3 endpoint for fresh data.
3. If the fetch succeeds and the envelope is valid, re-render from fresh data.
4. If the fetch fails, keep the snapshot visible and show a subtle stale or offline state.

Render from these v3 groups when present:

• identity: GlobalMetaID and display identity.
• profile: name, avatar metadata, bio, chat key hints, LLM/persona hints, and selected homepage declaration.
• presence: online or unknown hint only; unknown is not a profile error.
• sections.services: public skill services.
• sections.metaapps: MetaApps published by this Bot.
• sections.chats: recent outgoing chat peers, not chat history.
• sections.buzzes: recent public buzz content.
• warnings: low-priority non-fatal aggregation hints.

For profile.avatar and similar remote image fields, use the MetaFile image resolution rules above. If the v3 payload already contains a display-ready http(s) URL, render it directly. Only synthesize a fallback URL when the field is still a metafile://... reference, a bare pin id, or another recognized MetaFile content reference.

Treat profile.homepage.payload.uri as the selected custom homepage entry. Do not infer the selected homepage from sections.metaapps.

Do not depend on v1/v2-only fields such as top-level services, actions, proofs, source, chainName, or address fields. If a legacy homepage response must be consumed, handle it as a compatibility fallback only.

Bot homepage MetaApps should still follow MetaApp Development Rules: use metaid://, pin://, metaapp://, metafile://, and map:// links, and include the AgentBrowser helper when iframe navigation is needed.

After publishing a homepage MetaApp, ask whether to set it as the selected homepage for a local Bot. Only do this when the human explicitly wants the MetaApp to become that Bot homepage. Write through the existing Bot profile command:

{
  "homepage": {
    "uri": "metaapp://",
    "renderer": "metaapp",
    "contentType": "application/vnd.metaapp"
  }
}

$HOME/.metabot/bin/metabot bot update --from  --payload-file 

Clearing a Bot homepage is a separate Bot profile action and should not be bundled into ordinary MetaApp publishing.

Static Project Requirements

The app must be browser-runnable without a dedicated backend. Normal remote reads are allowed.

Accepted entry layouts:

index.html
dist/index.html
build/index.html
out/index.html
public/index.html

Include local assets needed by the page. Avoid absolute local filesystem paths. Avoid requiring a local development server for normal browsing. A Bot homepage project must also include data.json.

All packaged CSS, JS, image, font, document, JSON, and Markdown asset references must stay relative to the package entry or the referencing file. Do not publish a MetaApp that depends on site-root paths such as /assets/..., because Browser resolves those against the host origin instead of the packaged ZIP.

Publish Wizard

Use this path by default for natural-language "publish this ZIP/project/site as a MetaApp" requests. The wizard must collect fields, upload local assets first when needed, show the final MetaAPP JSON with real metafile://... references, and only then run metaapp publish or metaapp update.

Do not use publish-project as the default guided path. Keep it only as a fast path when the human explicitly asks for quick packaging and accepts that it bypasses guided JSON review.

1. Classify the source artifact.

• ZIP source: inspect enough to verify the declared indexFile exists.
• Project directory: preview to discover the artifact directory and default entry.

$HOME/.metabot/bin/metabot metaapp preview --project-dir 

If preview finds dist, build, out, public, or project-root index.html, package that browser-runnable directory into a ZIP while preserving relative paths. If preview cannot find an entry point, ask which built directory or default file should be used.

Before publishing, inspect entry HTML, CSS, and generated Markdown or templates for packaged asset references that start with /. If those files are expected to come from the ZIP, rewrite them to relative paths first.

1. Ask for required publish fields.

Required non-empty fields are title, appName, and content. content is the uploaded runtime ZIP metafile://... URI, so it becomes available after upload. If the human asks for defaults, use the directory or ZIP base name for title and a slugified version for appName.

1. Ask for recommended fields.

Ask for coverImg, icon, and intro. Also ask whether there are introImgs, tags, a version, a runtime, a custom indexFile, or source-code archive material for code.

Default field shape:

| Field | Default when not provided | |---|---| | title | Human-provided name, otherwise directory or ZIP base name | | appName | Human-provided app name, otherwise slugified title | | prompt | Empty string | | icon | Empty string unless a local image, HTTP(S) image URL, or metafile://... reference is provided | | coverImg | Empty string unless a local image, HTTP(S) image URL, or metafile://... reference is provided | | introImgs | Empty array | | intro | Empty string | | runtime | browser | | version | 1.0.0 | | `

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: openagentinternet
• Source: openagentinternet/open-agent-connect
• License: MIT

Install and usage instructions live in the source repository linked above.