Session source example

examples/session-source/
├── package.json       # manifest: one session source, one MCP install target
├── extension.js       # activate(): registers both
├── example-agent.js   # the two runtimes
└── test.mjs           # tests through @terminay/extension-api/testing

"terminay": {
  "manifestVersion": 1,
  "id": "com.example.agent",
  "displayName": "Example Agent",
  "description": "Shows Example Agent sessions in Terminay and registers the Terminay MCP server with it.",
  "api": "^3.0.0",
  "engines": { "terminay": ">=1.0.0", "node": ">=24" },
  "entrypoint": "extension.js",
  "platforms": ["darwin", "linux"],
  "permissions": ["agent-observation", "mcp-registration"],
  "contributes": {
    "agentSessionSources": [{
      "id": "com.example.agent/sessions",
      "displayName": "Example Agent",
      "harnesses": [{ "id": "example-agent", "displayName": "Example Agent" }],
      "environmentVariables": ["EXAMPLE_AGENT_HOME"]
    }],
    "mcpInstallTargets": [{
      "id": "com.example.agent/example-agent",
      "displayName": "Example Agent"
    }]
  }
}

import { defineExtension } from '@terminay/extension-api';
import {
  exampleMcpInstallTarget,
  exampleSessionSource,
} from './example-agent.js';

export default defineExtension({
  activate(context) {
    context.subscriptions.add(
      context.agents.registerSessionSource(
        'com.example.agent/sessions',
        exampleSessionSource,
      ),
    );
    context.subscriptions.add(
      context.mcp.registerInstallTarget(
        'com.example.agent/example-agent',
        exampleMcpInstallTarget,
      ),
    );
  },
});

export const exampleSessionSource = defineSessionSource({
  async start({ enabledHarnesses, publisher, signal, onEnabledHarnessesChanged }) {
    const directory = join(exampleHome(), 'sessions');
    await mkdir(directory, { recursive: true });
    let enabled = enabledHarnesses.includes('example-agent');
    const live = new Map(); // file name -> session id

    async function resetAll() {
      live.clear();
      if (!enabled) return publisher.reset([]);
      const sessions = [];
      for (const name of await readdir(directory)) {
        const session = await readSession(directory, name);
        if (!session) continue;
        live.set(name, session.id);
        sessions.push(session);
      }
      if (!signal.aborted) publisher.reset(sessions);
    }

    // Watch, never poll. Each event re-reads only the file it names.
    const watcher = watch(directory, { signal }, async (_event, name) => {
      if (!enabled || typeof name !== 'string') return;
      const session = await readSession(directory, name);
      if (signal.aborted) return;
      if (session) {
        live.set(name, session.id);
        publisher.upsert(session);
      } else if (live.has(name)) {
        publisher.remove(live.get(name));
        live.delete(name);
      }
    });
    watcher.on('error', () => {
      publisher.diagnostic({
        code: 'watch-failed',
        message: 'Example Agent sessions can no longer be watched',
      });
    });

    const subscription = onEnabledHarnessesChanged((next) => {
      enabled = next.includes('example-agent');
      void resetAll();
    });
    signal.addEventListener('abort', () => subscription.dispose(), { once: true });
    await resetAll();
  },
});