@ontrove/extend

The standard library for extending Trove — a personal knowledge base for AI. There are two things you can build, and they share one spine:

| Import | You are building | Entry point | |---|---|---| | @ontrove/extend/source | A source — a scheduled adapter that fetches content into the knowledge base. | defineSource({ sync }) | | @ontrove/extend/toolkit | A toolkit — tools an assistant calls live, hosted for you as an MCP server. | defineToolkit({ tools }) |

A source returns documents to be stored (a batch sync, resumable via a cursor); a toolkit's tools return results to be read live. Different contracts — but the parts you touch constantly are identical, because both are handed the same ExtensionContext: a credential, a guarded fetch, a log line, the clock. Knowing one means knowing the other.

The root import (@ontrove/extend) is that shared spine. @ontrove/extend/contract is the invoke contract every source runtime speaks, published so a third runtime can be held to it.

(Source authoring is an early, still-developing surface.) What this package does not yet own are the helpers a source is mostly written against — feed parsing, HTML to text, the scrape loop, the code that writes a cursor. Those still live alongside the sources themselves, so today the contract is shared and the implementation behind it is not. Moving them here is the direction of travel.

See the full SDK Reference, the manifest.json reference, and the cursors & feeds model in the docs.

Install

npm install @ontrove/extend

Quickstart

A source's index.ts must export default defineSource(...). Your sync fetches new content and returns documents — each field maps 1:1 onto the IngestDocumentInput the Mac app pushes via ingestDocuments.

Hacker News front page

import { defineSource } from '@ontrove/extend/source';

export default defineSource({
  // What the source IS. There is no separate manifest.json to keep in step —
  // it is generated from this, so the compiler is what notices a mistake.
  id: 'hacker-news',
  name: 'Hacker News',
  description: 'Front-page stories from Hacker News.',
  icon: '🔶',
  version: '1.0.0',
  author: 'you',
  kind: 'scheduled-sync',
  transport: 'api',
  cursor: 'date',
  ingest: 'append',
  runsIn: 'cloud',
  schedule: 'every 6 hours',
  status: 'implemented',
  needsBrowser: false,
  egress: ['hn.algolia.com'],

  // What it DOES.
  async sync(ctx) {
    const res = await ctx.fetch('https://hn.algolia.com/api/v1/search?tags=front_page');
    const { hits } = await res.json();
    ctx.log(`fetched ${hits.length} front-page stories`);

    return {
      documents: hits.map((hit) => ({
        id: hit.objectID, // → externalId; the dedup key
        title: hit.title,
        text: hit.story_text ?? hit.title,
        url: hit.url,
        author: hit.author,
        date: new Date(hit.created_at_i * 1000).toISOString(),
        contentType: 'bookmark',
      })),
      // Advance the cursor to the newest story's timestamp.
      cursor: { type: 'date', value: new Date(hits[0].created_at_i * 1000).toISOString() },
    };
  },
});

RSS feed (incremental, date cursor)

parseRss / stripHtml below are your own helpers — the SDK ships no XML parser. Bring your own (e.g. fast-xml-parser).

import { defineSource } from '@ontrove/extend/source';
// import { parseRss, stripHtml } from './rss-helpers'; // your own — see note above

export default defineSource({
  async sync(ctx) {
    const feedUrl = ctx.config.feedUrl as string;
    const since = ctx.cursor.type === 'date' ? new Date(ctx.cursor.value) : new Date(0);

    const res = await ctx.fetch(feedUrl);
    if (!res.ok) {
      // Throw to fail the run; the Mac app retries next tick. Already-pushed docs persist.
      throw new Error(`feed returned ${res.status} ${res.statusText}`);
    }

    const items = parseRss(await res.text()).filter((i) => new Date(i.pubDate) > since);
    const documents = items.map((item) => ({
      id: item.guid,
      title: item.title,
      text: stripHtml(item.contentEncoded ?? item.description),
      url: item.link,
      author: item.creator ?? feedUrl,
      date: item.pubDate,
    }));

    const newest = items[0]?.pubDate;
    return newest
      ? { documents, cursor: { type: 'date', value: newest } }
      : { documents };
  },
});

A bare array is accepted too — return documents; is shorthand for { documents } with no cursor change.

The ctx object

| Member | Type | Description | | ------------- | ------------------------------------------- | --------------------------------------------------------------------------- | | ctx.config | C (typed preferences) | The user's setup preferences. Never credentials. | | ctx.cursor | Cursor (read-only) | The feed's current cursor; { type: 'none' } on first sync. | | ctx.fetch | (url, init?) => Promise<Response> | Standard fetch — routes through the Mac app's networking. | | ctx.log | (...args) => void | Structured log entry, surfaced in the source's logs. | | ctx.now | () => Date | Injected clock (deterministic under test). |

ctx.credentials (Keychain-resolved auth) and ctx.browser (Playwright) are proposed, not part of the shipped contract, and intentionally absent.

The document shape → IngestDocumentInput

Document maps 1:1 onto the GraphQL IngestDocumentInput wire type:

| Document | IngestDocumentInput | Required | | ------------------- | --------------------- | ------------------------------ | | id | externalId | Yes | | title | title | No | | text | text | One of text / audioUrl | | audioUrl | audioUrl | One of text / audioUrl | | url | url | No | | author | author | No | | date | date (ISO 8601) | No | | tags | tags | No | | metadata | metadata (JSON) | No | | contentType | contentType | No (default text) |

Dedup is keyed on (feed, id), so sync is safe to retry — re-returning the same id is skipped.

Cursors

A Cursor describes how a feed resumes between syncs:

• { type: 'date', value } — time-ordered feeds with "since <date>" filtering (RSS, most APIs).
• { type: 'idSet', values, max? } — no reliable date filter, so resuming means remembering which ids you have. max caps how many are retained; it is a count, not an id.
• { type: 'none' } — re-fetch everything; rely on dedup. Always correct, less efficient.

Local run harness

runSource is what trove source dev / trove source test call. It builds a ctx, runs sync, validates and dedups the documents:

import { runSource } from '@ontrove/extend/source';
import source from './index.js';

const { documents, cursor, duplicatesSkipped } = await runSource(source, {
  config: { feedUrl: 'https://example.com/feed.xml' },
  cursor: { type: 'date', value: '2026-06-01T00:00:00Z' },
});

Manifest validation

validateSourceManifest backs trove source validate. It checks required fields and the id/version patterns, and lints config for credential-shaped keys — the same spirit as the cloud's validateConfig (config holds preferences only; credentials live in the macOS Keychain).

import { validateSourceManifest } from '@ontrove/extend/source';

const { valid, errors } = validateSourceManifest(manifest);
if (!valid) throw new Error(errors.join('\n'));

Support

Guides and the full reference live at docs.ontrove.sh.

Report bugs or security issues to [email protected].

License

Released under the MIT License. © 2026 Hollyburn Analytics Inc.