Implementation Guide

{
  success: true,
  data: { status: 'print_dialog_opened', message: 'Print dialog opened.' }
}

// Wrong: Depends on previous state.setContent call
async _exportPdf() {
  // Exports whatever the page is currently showing
  window.print();
  return { success: true, data: { rendered: true } };
}

// Correct: Self-contained -- uses the input parameter
async _exportPdf({ content, contentType = 'html' }) {
  // Process content if needed (e.g., convert raw data to HTML)
  const html = contentType === 'html' ? content : renderToHtml(content);

  // Render the INPUT PARAMETER into print container
  const container = document.getElementById('print-container');
  container.innerHTML = html;

  window.print();
  return { success: true, data: { rendered: true } };
}

<link rel="abp-manifest" href="/abp.json">

{
  "abp": "0.1",
  "app": {
    "id": "com.example.myapp",
    "name": "My App",
    "version": "1.0.0",
    "description": "Brief description of your app"
  },
  "capabilities": [
    {
      "name": "convert.markdownToHtml",
      "description": "Convert Markdown to HTML",
      "inputSchema": {
        "type": "object",
        "properties": {
          "markdown": {
            "type": "string",
            "description": "Markdown content to convert"
          },
          "options": {
            "type": "object",
            "properties": {
              "gfm": { "type": "boolean", "description": "Enable GitHub Flavored Markdown" }
            }
          }
        },
        "required": ["markdown"]
      }
    },
    {
      "name": "export.html",
      "description": "Export content as HTML document",
      "inputSchema": {
        "type": "object",
        "properties": {
          "html": {
            "type": "string",
            "description": "HTML content to export"
          },
          "options": {
            "type": "object",
            "properties": {
              "filename": { "type": "string", "description": "Suggested filename" }
            }
          }
        },
        "required": ["html"]
      }
    }
  ]
}

window.abp = {
  // Identity (synchronous, always present)
  protocolVersion, app, initialized, sessionId,

  // Methods (async operations)
  initialize(), shutdown(), call(), listCapabilities()
};

window.abp = {
  // Identity
  protocolVersion: '0.1',
  app: {
    id: 'com.example.myapp',
    name: 'My App',
    version: '1.0.0'
  },

  // Session state
  initialized: false,
  sessionId: null,

  // Initialize session
  async initialize(params) {
    this.initialized = true;
    this.sessionId = crypto.randomUUID();

    return {
      sessionId: this.sessionId,
      protocolVersion: '0.1',
      app: this.app,
      capabilities: [
        { name: 'convert.markdownToHtml', available: true },
        { name: 'export.html', available: true }
      ],
      features: {
        notifications: false,
        progress: false,
        elicitation: false,
        dynamicCapabilities: false
      }
    };
  },

  // Shutdown session
  async shutdown() {
    this.initialized = false;
    this.sessionId = null;
  },

  // Call a capability
  async call(capability, params = {}) {
    if (!this.initialized) {
      return {
        success: false,
        error: {
          code: 'NOT_INITIALIZED',
          message: 'Call initialize() first',
          retryable: true
        }
      };
    }

    switch (capability) {
      case 'convert.markdownToHtml':
        return await this._convertMarkdownToHtml(params);
      case 'export.html':
        return await this._exportHtml(params);
      default:
        return {
          success: false,
          error: {
            code: 'UNKNOWN_CAPABILITY',
            message: `Unknown capability: ${capability}`,
            retryable: false
          }
        };
    }
  },

  // List all capabilities with runtime details
  async listCapabilities() {
    return [
      {
        name: 'convert.markdownToHtml',
        description: 'Convert Markdown to HTML',
        available: true
      },
      {
        name: 'export.html',
        description: 'Export content as HTML document',
        available: true
      }
    ];
  },

  // --- Capability handlers below ---
  // (See patterns for each type)
};

async _convertMarkdownToHtml({ markdown, options = {} }) {
  try {
    // Use the SAME library your app already uses
    const html = marked.parse(markdown, {
      gfm: options.gfm !== false,
      breaks: options.breaks || false
    });

    return {
      success: true,
      data: { html }
    };
  } catch (error) {
    return {
      success: false,
      error: {
        code: 'CONVERSION_ERROR',
        message: error.message,
        retryable: false
      }
    };
  }
}

async _exportHtml({ html, options = {} }) {
  const filename = options.filename || 'export.html';

  // For text content
  return {
    success: true,
    data: {
      document: {
        content: html,
        mimeType: 'text/html',
        encoding: 'utf-8',
        size: new Blob([html]).size,
        filename: filename
      }
    }
  };
}

async _exportImage({ imageData, options = {} }) {
  // imageData is already a base64 string from canvas.toDataURL()
  return {
    success: true,
    data: {
      document: {
        content: imageData,
        mimeType: 'image/png',
        encoding: 'base64',
        size: atob(imageData).length,
        filename: options.filename || 'export.png'
      }
    }
  };
}

async _processImage({ imageData, operations = [] }) {
  try {
    const img = new Image();
    img.src = imageData;
    await new Promise((resolve, reject) => {
      img.onload = resolve;
      img.onerror = reject;
    });

    const canvas = document.createElement('canvas');
    canvas.width = img.width;
    canvas.height = img.height;
    const ctx = canvas.getContext('2d');
    ctx.drawImage(img, 0, 0);

    // Apply operations (resize, crop, etc.)
    for (const op of operations) {
      if (op.type === 'resize') {
        canvas.width = op.width;
        canvas.height = op.height;
        ctx.drawImage(img, 0, 0, op.width, op.height);
      }
    }

    const resultData = canvas.toDataURL('image/png');
    return {
      success: true,
      data: {
        image: resultData,
        mimeType: 'image/png',
        width: canvas.width,
        height: canvas.height
      }
    };
  } catch (error) {
    return {
      success: false,
      error: {
        code: 'OPERATION_FAILED',
        message: error.message,
        retryable: false
      }
    };
  }
}

// Simple: App returns content -- agent/client handles PDF delivery
async _convertMarkdownToHtml({ markdown, options = {} }) {
  const html = marked.parse(markdown, { gfm: options.gfm !== false });
  return { success: true, data: { html } };
}

// Advanced: Prepare content in app context, signal transport
async _exportPdf({ html, options = {} }) {
  const container = document.getElementById('print-container');
  container.innerHTML = html;
  await document.fonts.ready;
  window.print(); // Transport signal -- intercepted by Puppeteer-based clients
  return { success: true, data: { rendered: true } };
}

// Fallback: Return PDF as BinaryData (transport-agnostic)
async _exportPdf({ html, options = {} }) {
  const response = await fetch('/api/generate-pdf', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ html, options })
  });
  const pdfBlob = await response.blob();
  const arrayBuffer = await pdfBlob.arrayBuffer();
  const base64 = btoa(String.fromCharCode(...new Uint8Array(arrayBuffer)));
  return {
    success: true,
    data: {
      document: {
        content: base64,
        mimeType: 'application/pdf',
        encoding: 'base64',
        size: pdfBlob.size,
        filename: options.filename || 'export.pdf'
      }
    }
  };
}

// Your app's existing code
function savePdf() {
  const printWindow = window.open('', '_blank');
  printWindow.document.write(getStyledHtml());
  printWindow.print();
  printWindow.close();
}

// ABP adaptation: expose the content
async _renderHtml({ data, options = {} }) {
  const html = getStyledHtml(data); // Reuse existing function
  return { success: true, data: { html } };
}

// Forbidden
const ok = confirm('Delete all items?');

// ABP Alternative
const response = await abp.elicit({
  method: 'elicitation/confirm',
  params: {
    message: 'Delete all items? This cannot be undone.',
    destructive: true
  },
  timeout: 30000
});
const ok = response.success && response.data.confirmed;

// Wrong: Triggers browser download -- agent can't access the file
async _exportFile({ content, mimeType, filename }) {
  const blob = new Blob([content], { type: mimeType });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  URL.revokeObjectURL(url);

  return {
    success: true,
    data: { status: 'download_started', filename: filename }
  };
}

// Correct: Return the data in the response
async _exportFile({ content, mimeType, filename }) {
  const base64 = btoa(unescape(encodeURIComponent(content)));

  return {
    success: true,
    data: {
      file: {
        content: base64,
        mimeType: mimeType,
        encoding: 'base64',
        size: new Blob([content]).size,
        filename: filename
      }
    }
  };
}

// Wrong: Writes to the browser's clipboard -- useless to an agent in a separate process
async _copyAsHtml({ markdown }) {
  const html = marked.parse(markdown);
  await navigator.clipboard.writeText(html);
  return {
    success: true,
    data: { status: 'copied_to_clipboard' }
  };
}

// Correct: Return the content -- agent uses host tools (pbcopy, xclip, clip) if it needs clipboard
async _convertMarkdownToHtml({ markdown, options = {} }) {
  const html = marked.parse(markdown, { gfm: options.gfm !== false });
  return {
    success: true,
    data: { html }
  };
}

// Wrong: Opens native share dialog -- agent can't select a share target
async _shareContent({ title, text, url }) {
  await navigator.share({ title, text, url });
  return {
    success: true,
    data: { status: 'share_dialog_opened' }
  };
}

// Correct: Return the shareable data -- agent routes as needed
async _getShareableData({ contentId }) {
  const content = await loadContent(contentId);
  return {
    success: true,
    data: {
      title: content.title,
      text: content.summary,
      url: content.publicUrl
    }
  };
}

{
  "name": "hardware.cameraCapture",
  "description": "Capture image from device camera",
  "requirements": [
    {
      "type": "permission",
      "description": "Camera access permission required",
      "met": false,
      "resolution": "Grant camera permission to the page origin"
    }
  ],
  "inputSchema": {
    "type": "object",
    "properties": {
      "resolution": { "type": "string", "enum": ["low", "medium", "high"] }
    }
  }
}

async _cameraCapture({ resolution = 'medium' }) {
  try {
    const constraints = {
      video: { width: resolution === 'high' ? 1920 : resolution === 'medium' ? 1280 : 640 }
    };
    const stream = await navigator.mediaDevices.getUserMedia(constraints);
    const track = stream.getVideoTracks()[0];
    const imageCapture = new ImageCapture(track);
    const bitmap = await imageCapture.grabFrame();
    track.stop();

    const canvas = document.createElement('canvas');
    canvas.width = bitmap.width;
    canvas.height = bitmap.height;
    canvas.getContext('2d').drawImage(bitmap, 0, 0);

    return {
      success: true,
      data: {
        image: canvas.toDataURL('image/png'),
        mimeType: 'image/png',
        width: bitmap.width,
        height: bitmap.height
      }
    };
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      return {
        success: false,
        error: {
          code: 'PERMISSION_DENIED',
          message: 'Camera access permission denied',
          retryable: true,
          retryAfter: 1000
        }
      };
    }
    throw err;
  }
}

{
  success: true,
  data: {
    document: {
      content: '...',            // The content (string or base64)
      mimeType: 'text/html',     // REQUIRED: MIME type
      encoding: 'utf-8',         // REQUIRED for strings: 'utf-8' or 'base64'
      size: 4523,                // RECOMMENDED: size in bytes
      filename: 'export.html'    // OPTIONAL: suggested filename
    }
  }
}

{
  success: true,
  data: {
    document: {
      downloadUrl: 'https://example.com/files/abc123',
      mimeType: 'application/pdf',
      size: 15000000,
      filename: 'large-export.pdf'
    }
  }
}

// Consistent: Both return data in the same structure

// export.html response:
{ success: true, data: { document: { content: '<html>...</html>', mimeType: 'text/html', encoding: 'utf-8', size: 4523, filename: 'export.html' } } }

// export.csv response:
{ success: true, data: { document: { content: 'name,age\nAlice,30', mimeType: 'text/csv', encoding: 'utf-8', size: 22, filename: 'export.csv' } } }

{
  code: 'ERROR_CODE',       // REQUIRED: machine-readable error code (see table below)
  message: 'Human-readable description of what went wrong',  // REQUIRED
  retryable: false          // REQUIRED: whether the agent should retry the call
}

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Markdown Converter</title>
  <link rel="abp-manifest" href="/abp.json">
</head>
<body>
  <h1>Markdown Converter</h1>
  <textarea id="input" placeholder="Enter markdown..."></textarea>
  <div id="preview"></div>

  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
  <script src="/abp-runtime.js"></script>
</body>
</html>

{
  "abp": "0.1",
  "app": {
    "id": "com.example.markdown-converter",
    "name": "Markdown Converter",
    "version": "1.0.0",
    "description": "Convert Markdown to HTML"
  },
  "capabilities": [
    {
      "name": "convert.markdownToHtml",
      "description": "Convert Markdown text to HTML",
      "inputSchema": {
        "type": "object",
        "properties": {
          "markdown": { "type": "string", "description": "Markdown content to convert" },
          "options": {
            "type": "object",
            "properties": {
              "gfm": { "type": "boolean", "description": "Enable GitHub Flavored Markdown" }
            }
          }
        },
        "required": ["markdown"]
      }
    },
    {
      "name": "export.html",
      "description": "Export content as HTML document",
      "inputSchema": {
        "type": "object",
        "properties": {
          "html": { "type": "string", "description": "HTML content to export" },
          "options": {
            "type": "object",
            "properties": {
              "filename": { "type": "string", "description": "Suggested filename" }
            }
          }
        },
        "required": ["html"]
      }
    }
  ]
}

window.abp = {
  protocolVersion: '0.1',
  app: { id: 'com.example.markdown-converter', name: 'Markdown Converter', version: '1.0.0' },
  initialized: false,
  sessionId: null,

  async initialize(params) {
    this.initialized = true;
    this.sessionId = crypto.randomUUID();
    return {
      sessionId: this.sessionId,
      protocolVersion: '0.1',
      app: this.app,
      capabilities: [
        { name: 'convert.markdownToHtml', available: true },
        { name: 'export.html', available: true }
      ],
      features: {
        notifications: false,
        progress: false,
        elicitation: false,
        dynamicCapabilities: false
      }
    };
  },

  async shutdown() {
    this.initialized = false;
    this.sessionId = null;
  },

  async call(capability, params = {}) {
    if (!this.initialized) {
      return {
        success: false,
        error: { code: 'NOT_INITIALIZED', message: 'Call initialize() first', retryable: true }
      };
    }

    switch (capability) {
      case 'convert.markdownToHtml':
        return await this._convertMarkdownToHtml(params);
      case 'export.html':
        return await this._exportHtml(params);
      default:
        return {
          success: false,
          error: { code: 'UNKNOWN_CAPABILITY', message: `Unknown capability: ${capability}`, retryable: false }
        };
    }
  },

  // List all capabilities with runtime details
  async listCapabilities() {
    return [
      {
        name: 'convert.markdownToHtml',
        description: 'Convert Markdown text to HTML',
        available: true
      },
      {
        name: 'export.html',
        description: 'Export content as HTML document',
        available: true
      }
    ];
  },

  // --- Capability Handlers ---

  async _convertMarkdownToHtml({ markdown, options = {} }) {
    try {
      const html = marked.parse(markdown, {
        gfm: options.gfm !== false,
        breaks: options.breaks || false
      });
      return { success: true, data: { html } };
    } catch (error) {
      return {
        success: false,
        error: { code: 'CONVERSION_ERROR', message: error.message, retryable: false }
      };
    }
  },

  async _exportHtml({ html, options = {} }) {
    const filename = options.filename || 'export.html';

    return {
      success: true,
      data: {
        document: {
          content: html,
          mimeType: 'text/html',
          encoding: 'utf-8',
          size: new Blob([html]).size,
          filename: filename
        }
      }
    };
  }
};