Build a Custom Adapter

import {
  defineAdapter,
  installAssetFile,
  readAssetFile,
  deleteAssetFile,
  type Scope,
  type AssetType,
  type Validated,
  type AdapterMetadata,
} from '@agent-facets/adapter'
import { homedir } from 'node:os'
import { join } from 'node:path'

// Where an asset of a given type lives on disk for this tool.
function assetPath(assetType: AssetType, name: string): { file: string } {
  return { file: join(homedir(), '.my-tool', `${assetType}s`, `${name}.md`) }
}

export default defineAdapter({
  name: 'my-tool',
  supportsInstall: true,

  // Validate + enrich the author's `adapters.my-tool` block. Return the
  // metadata you want written as front-matter, or errors if it's invalid.
  buildAssetMetadata(data: unknown): Validated<AdapterMetadata> {
    // Trivial pass-through; use arktype/zod here for a real schema.
    const meta = (data ?? {}) as AdapterMetadata
    return { ok: true, data: meta }
  },

  // Write the asset. `content` is the asset body; `metadata` becomes
  // YAML front-matter. installAssetFile handles the front-matter assembly,
  // directory creation, and idempotent overwrite for you.
  async installAsset(scope: Scope, assetType: AssetType, name: string, content: string, metadata: unknown) {
    return installAssetFile(assetPath(assetType, name), content, metadata as AdapterMetadata)
  },

  async readAsset(scope: Scope, assetType: AssetType, name: string) {
    return readAssetFile(assetPath(assetType, name))
  },

  async deleteAsset(scope: Scope, assetType: AssetType, name: string) {
    return deleteAssetFile(assetPath(assetType, name))
  },
})