Extension context

activate(context) receives the complete public extension context. It holds one registration surface per contribution type, the extension's own directories, and a subscription set.

Use it in activate

TypeScript 
import { defineExtension } from '@terminay/extension-api';

export default defineExtension({
  activate(context) {
    context.subscriptions.add(
      context.agents.registerSessionSource('com.example.agent/sessions', sessionSource),
    );
    context.subscriptions.add(
      context.mcp.registerInstallTarget('com.example.agent/example-agent', installTarget),
    );
  },
  async deactivate() {
    // Optional extension-owned cleanup.
  },
});

Default-export the value returned by defineExtension(). It takes activate and an optional deactivate; both may return a promise.

Context members

TypeScript 
interface ExtensionContext {
  extensionId: string;
  apiVersion: string;
  paths: { configuration: string; data: string; cache: string };
  agents: AgentSessionSourceRegistry;
  mcp: McpInstallTargetRegistry;
  worktrees: WorktreeInsightSourceRegistry;
  subscriptions: ExtensionSubscriptions;
  registerLanguageServerProvider(registration: LanguageServerRegistration): void;
}
MemberUse
extensionIdThe immutable ID from the manifest.
apiVersionThe Extension API version the host implements.
paths.configuration, paths.data, paths.cacheThis extension's own configuration, durable data, and cache directories.
agents.registerSessionSource(sourceId, runtime)Register a declared agent session source. Returns a disposable registration with sourceId.
mcp.registerInstallTarget(targetId, runtime)Register a declared MCP install target. Returns a disposable registration with targetId.
worktrees.registerInsightSource(sourceId, runtime)Register a declared worktree insight source. Returns a disposable registration with sourceId.
registerLanguageServerProvider(registration)Register a declared language server with an id and a runtime. Returns nothing.
subscriptions.add(disposable)Hand the host a Disposable to dispose when the activation ends. Returns the same disposable.

Registration rules

  • Every ID must be declared by this extension's manifest. An undeclared ID throws.
  • Registering the same ID twice throws.
  • Session sources, MCP install targets, and worktree insight sources also need their permission: agent-observation, mcp-registration, and worktree-observation.
  • Register during activate. The host reads the registered set when activation completes.

Lifecycle and boundaries

  • Disposable.dispose() may be synchronous or return a promise, and must be safe to call more than once.
  • Terminay disposes the subscription set, in reverse order, when the extension is disabled, updated, or shut down.
  • Long-running runtimes receive an AbortSignal. Release every watch and timer when it aborts; later publisher calls are ignored.
  • The context does not expose renderer UI, routes, Electron, raw PTYs, host transports, or private Terminay packages.