a ctfer on the load

1
/**
2
 * Discover extensions in a directory.
3
 *
4
 * Discovery rules:
5
 * 1. Direct files: `extensions/*.ts` or `*.js` → load
6
 * 2. Subdirectory with index: `extensions/* /index.ts` or `index.js` → load
7
 * 3. Subdirectory with package.json: `extensions/* /package.json` with "pi" field → load what it declares
8
 *
9
 * No recursion beyond one level. Complex packages must use package.json manifest.
10
 */
11
function discoverExtensionsInDir(dir: string): string[] {
12
  if (!fs.existsSync(dir)) {
13
    return [];
14
  }
15

16
  const discovered: string[] = [];
17

18
  try {
19
    const entries = fs.readdirSync(dir, { withFileTypes: true });
20

21
    for (const entry of entries) {
22
      const entryPath = path.join(dir, entry.name);
23

24
      // 1. Direct files: *.ts or *.js
25
      if ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {
26
        discovered.push(entryPath);
27
        continue;
28
      }
29

30
      // 2 & 3. Subdirectories
31
      if (entry.isDirectory() || entry.isSymbolicLink()) {
32
        const entries = resolveExtensionEntries(entryPath);
33
        if (entries) {
34
          discovered.push(...entries);
35
        }
36
      }
37
    }
38
  } catch {
39
    return [];
40
  }
41

42
  return discovered;
43
}

1
/**
2
 * Resolve extension entry points from a directory.
3
 *
4
 * Checks for:
5
 * 1. package.json with "pi.extensions" field -> returns declared paths
6
 * 2. index.ts or index.js -> returns the index file
7
 *
8
 * Returns resolved paths or null if no entry points found.
9
 */
10
function resolveExtensionEntries(dir: string): string[] | null {
11
  // Check for package.json with "pi" field first
12
  const packageJsonPath = path.join(dir, "package.json");
13
  if (fs.existsSync(packageJsonPath)) {
14
    const manifest = readPiManifest(packageJsonPath);
15
    if (manifest?.extensions?.length) {
16
      const entries: string[] = [];
17
      for (const extPath of manifest.extensions) {
18
        const resolvedExtPath = path.resolve(dir, extPath);
19
        if (fs.existsSync(resolvedExtPath)) {
20
          entries.push(resolvedExtPath);
21
        }
22
      }
23
      if (entries.length > 0) {
24
        return entries;
25
      }
26
    }
27
  }
28

29
  // Check for index.ts or index.js
30
  const indexTs = path.join(dir, "index.ts");
31
  const indexJs = path.join(dir, "index.js");
32
  if (fs.existsSync(indexTs)) {
33
    return [indexTs];
34
  }
35
  if (fs.existsSync(indexJs)) {
36
    return [indexJs];
37
  }
38

39
  return null;
40
}

1
async function loadExtensionModule(extensionPath: string, cacheToken?: ExtensionCacheToken) {
2
  if (isCurrentCacheToken(cacheToken)) {
3
    const cachedFactory = extensionCache.get(extensionPath);
4
    if (cachedFactory) {
5
      return cachedFactory;
6
    }
7
  }
8

9
  const createJitiImpl = await getCreateJiti();
10
  // Compiled binaries and the bundled Node distribution use embedded modules.
11
  // Source TypeScript reuses host modules and root tsconfig paths. Unbundled
12
  // Node builds use dist aliases and do not need the bundled virtual modules.
13
  const resolutionOptions = usesEmbeddedModules
14
    ? { virtualModules: await getVirtualModules(), tryNative: false }
15
    : isTypeScriptSourceRuntime
16
      ? { virtualModules: await getVirtualModules(), tsconfigPaths: true }
17
      : { alias: getAliases() };
18
  const jiti = createJitiImpl(import.meta.url, {
19
    moduleCache: false,
20
    ...resolutionOptions,
21
  });
22

23
  const module = await jiti.import(extensionPath, { default: true });
24
  const factory = module as ExtensionFactory;
25
  if (typeof factory !== "function") {
26
    return undefined;
27
  }
28
  if (isCurrentCacheToken(cacheToken)) {
29
    extensionCache.set(extensionPath, factory);
30
  }
31
  return factory;
32
}

1
const isNodeSeaBinary =
2
  ("sea" in process.features && process.features.sea === true) ||
3
  process.getBuiltinModule("node:sea")?.isSea() === true;
4
const isTypeScriptSourceRuntime = !isBunBinary && path.extname(fileURLToPath(import.meta.url)) === ".ts";
5
const usesEmbeddedModules = isBunBinary || isNodeSeaBinary || isBundledNode;

1
function getAliases(): Record<string, string> {
2
  if (_aliases) return _aliases;
3

4
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
5
  const packageIndex = path.resolve(__dirname, "../..", "index.js");
6

7
  const typeboxEntry = require.resolve("typebox");
8
  const typeboxCompileEntry = require.resolve("typebox/compile");
9
  const typeboxValueEntry = require.resolve("typebox/value");
10

11
  const packagesRoot = path.resolve(__dirname, "../../../../");
12
  const resolveWorkspaceOrImport = (workspaceRelativePath: string, specifier: string): string => {
13
    const workspacePath = path.join(packagesRoot, workspaceRelativePath);
14
    if (fs.existsSync(workspacePath)) {
15
      return workspacePath;
16
    }
17
    return fileURLToPath(import.meta.resolve(specifier));
18
  };
19

20
  const piCodingAgentEntry = packageIndex;
21
  const piAgentCoreEntry = resolveWorkspaceOrImport("agent/dist/index.js", "@earendil-works/pi-agent-core");
22
  const piTuiEntry = resolveWorkspaceOrImport("tui/dist/index.js", "@earendil-works/pi-tui");
23
  // Extensions resolve the pi-ai root to the compat entrypoint (a strict
24
  // superset of the core entrypoint): existing extensions using the old
25
  // global API keep working at runtime until compat is removed.
26
  const piAiCompatEntry = resolveWorkspaceOrImport("ai/dist/compat.js", "@earendil-works/pi-ai/compat");
27
  const piAiOauthEntry = resolveWorkspaceOrImport("ai/dist/oauth.js", "@earendil-works/pi-ai/oauth");
28
  const piAiProvidersEntry = resolveWorkspaceOrImport(
29
    "ai/dist/providers/all.js",
30
    "@earendil-works/pi-ai/providers/all",
31
  );
32

33
  _aliases = {
34
    "@earendil-works/pi-coding-agent": piCodingAgentEntry,
35
    "@earendil-works/pi-agent-core": piAgentCoreEntry,
36
    "@earendil-works/pi-tui": piTuiEntry,
37
    "@earendil-works/pi-ai/providers/all": piAiProvidersEntry,
38
    "@earendil-works/pi-ai/compat": piAiCompatEntry,
39
    "@earendil-works/pi-ai/oauth": piAiOauthEntry,
40
    "@earendil-works/pi-ai": piAiCompatEntry,
41
    "@mariozechner/pi-coding-agent": piCodingAgentEntry,
42
    "@mariozechner/pi-agent-core": piAgentCoreEntry,
43
    "@mariozechner/pi-tui": piTuiEntry,
44
    "@mariozechner/pi-ai/providers/all": piAiProvidersEntry,
45
    "@mariozechner/pi-ai/compat": piAiCompatEntry,
46
    "@mariozechner/pi-ai/oauth": piAiOauthEntry,
47
    "@mariozechner/pi-ai": piAiCompatEntry,
48
    typebox: typeboxEntry,
49
    "typebox/compile": typeboxCompileEntry,
50
    "typebox/value": typeboxValueEntry,
51
    "@sinclair/typebox": typeboxEntry,
52
    "@sinclair/typebox/compile": typeboxCompileEntry,
53
    "@sinclair/typebox/value": typeboxValueEntry,
54
  };
55

56
  return _aliases;
57
}

1
    on(event: string, handler: HandlerFn): () => void {
2
      assertActive();
3
      const registeredHandler: HandlerFn = (...args) => handler(...args);
4
      const list = extension.handlers.get(event) ?? [];
5
      list.push(registeredHandler);
6
      extension.handlers.set(event, list);
7

8
      return () => {
9
        const handlers = extension.handlers.get(event);
10
        if (!handlers) return;
11
        const handlerIndex = handlers.indexOf(registeredHandler);
12
        if (handlerIndex === -1) return;
13
        handlers.splice(handlerIndex, 1);
14
        if (handlers.length === 0) extension.handlers.delete(event);
15
      };
16
    },
17

18
    registerTool(tool: ToolDefinition): void {
19
      assertActive();
20
      if (typeof tool.parameters !== "object" || tool.parameters === null || Array.isArray(tool.parameters)) {
21
        throw new Error(
22
          `Tool "${tool.name}" registered by extension "${extension.path}" must define an object parameter schema.`,
23
        );
24
      }
25
      extension.tools.set(tool.name, {
26
        definition: tool,
27
        sourceInfo: extension.sourceInfo,
28
      });
29
      runtime.refreshTools();
30
    },

1
async function initializeExtension(
2
  factory: ExtensionFactory,
3
  extensionPath: string,
4
  resolvedPath: string,
5
  cwd: string,
6
  eventBus: EventBus,
7
  runtime: ExtensionRuntime,
8
): Promise<Extension> {
9
  const extension = createExtension(extensionPath, resolvedPath);
10
  const load = createExtensionAPI(extension, runtime, cwd, eventBus);
11
  try {
12
    await factory(load.api);
13
    load.commit();
14
  } catch (error) {
15
    load.discard();
16
    throw error;
17
  }
18
  time(`${extensionPath} factory`, "extensions");
19
  return extension;
20
}

1
const applyRuntimeChange = (change: () => void) => {
2
    if (state === "loading") pendingRuntimeChanges.push(change);
3
    else change();
4
};

1
commit: () => {
2
    if (state !== "loading") return;
3
    runtime.assertActive();
4
    for (const [name, value] of pendingFlagValues) {
5
        if (!runtime.flagValues.has(name)) runtime.flagValues.set(name, value);
6
    }
7
    for (const apply of pendingRuntimeChanges) apply();
8
    state = "active";
9
    clearPending();
10
},
11
discard: () => {
12
    if (state !== "loading") return;
13
    state = "failed";
14
    for (const unsubscribe of loadingUnsubscribers) unsubscribe();
15
    clearPending();
16
},

1
const assertActive = () => {
2
    if (state === "failed") {
3
        throw new Error(`Extension "${extension.path}" failed to load and its API is no longer active.`);
4
    }
5
    runtime.assertActive();
6
};

1
createContext(): ExtensionContext {
2
    const runner = this;
3
    const getModel = this.getModel;
4
    return {
5
        get ui()          { runner.assertActive(); return runner.uiContext; },
6
        get mode()        { runner.assertActive(); return runner.mode; },
7
        get cwd()         { runner.assertActive(); return runner.cwd; },
8
        get signal()      { runner.assertActive(); return getSignalFn(); },
9
        isIdle: () => { runner.assertActive(); return runner.isIdleFn(); },
10
        abort: () => { runner.assertActive(); runner.abortFn(); },
11
        getContextUsage: () => { runner.assertActive(); return runner.getContextUsageFn(); },
12
        ...
13
    };
14
}

1
createCommandContext(): ExtensionCommandContext {
2
    // Use property descriptors instead of object spread so the guarded getters from
3
    // createContext() stay lazy. A spread would eagerly read them once and freeze the
4
    // old values into the returned object, bypassing stale-instance checks.
5
    const context = Object.defineProperties(
6
        {},
7
        Object.getOwnPropertyDescriptors(this.createContext()),
8
    ) as ExtensionCommandContext;

1
createToolContext(toolCallId: string, signal: AbortSignal | undefined): ExtensionToolContext {
2
    const runner = this;
3
    // createContext() returns a fresh object, so adding properties does not affect other contexts.
4
    return Object.defineProperties(this.createContext() as ExtensionToolContext, {
5
        tools: { get() { runner.assertActive(); return runner.getCallableToolsFn(); } },
6
        executeTool: {
7
            value: async (name: string, args: unknown, options: ExecuteToolOptions = {}) => {
8
                runner.assertActive();
9
                ...
10
            },
11
        },
12
    });
13
}

1
const noOpUIContext: ExtensionUIContext = {
2
    select: async () => undefined,
3
    confirm: async () => false,
4
    input: async () => undefined,
5
    notify: () => {},
6
    custom: async () => undefined as never,
7
    setTheme: (_theme: string | Theme) => ({ success: false, error: "UI not available" }),
8
    ...
9
};

1
function snapshotEventHandlers(extensions: Extension[], event: ExtensionEvent["type"]) {
2
    return extensions.map((ext) => ({ ext, handlers: ext.handlers.get(event)?.slice() ?? [] }));
3
}

1
invalidate(message = "This extension ctx is stale after session replacement or reload. ..."): void {
2
    if (!this.staleMessage) {
3
        this.staleMessage = message;
4
        this.runtime.invalidate(message);
5
    }
6
}
7

8
private assertActive(): void {
9
    if (this.staleMessage) {
10
        throw new Error(this.staleMessage);
11
    }
12
}

1
async reload(options?): Promise<void> {
2
    const oldRunner = this._extensionRunner;
3
    const previousFlagValues = oldRunner.getFlagValues();
4
    await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });
5
    oldRunner.invalidate();
6
    // ... settingsManager.reload() / resetApiProviders() / _resourceLoader.reload()
7
    for (const name of this.getActiveToolNames()) this._pendingToolNames.add(name);
8
    this._buildRuntime({
9
        activeToolNames: [...this.getActiveToolNames(), ...addedDefaultTools],
10
        flagValues: previousFlagValues,
11
        includeAllExtensionTools: true,
12
    });
13
    if (hasBindings) {
14
        await options?.beforeSessionStart?.();
15
        await this._extensionRunner.emit({ type: "session_start", reason: "reload" });
16
        this._extensionRunner.reportUnhandledMcpServers();
17
        await this.extendResourcesFromExtensions("reload");
18
    }
19
}

1
/**
2
 * Install tool hooks once on the Agent instance.
3
 * The callbacks read `this._extensionRunner` at execution time, so extension reload swaps in the
4
 * new runner without reinstalling hooks.
5
 */
6
private _installAgentToolHooks(): void {
7
    this.agent.beforeToolCall = (context) => this._beforeToolCall(context);
8
    this.agent.afterToolCall = (context) => this._afterToolCall(context);
9
}

1
private async _beforeToolCall({ toolCall, args }, parentToolCallId?): Promise<BeforeToolCallResult | undefined> {
2
    const runner = this._extensionRunner;
3
    if (!runner.hasHandlers("tool_call")) {
4
        return undefined;
5
    }
6
    ...
7
}

1
export function createEventBus(): EventBusController {
2
    const emitter = new EventEmitter();
3
    return {
4
        emit: (channel, data) => { emitter.emit(channel, data); },
5
        on: (channel, handler) => {
6
            const safeHandler = async (data: unknown) => {
7
                try { await handler(data); }
8
                catch (err) { console.error(`Event handler error (${channel}):`, err); }
9
            };
10
            emitter.on(channel, safeHandler);
11
            return () => emitter.off(channel, safeHandler);
12
        },
13
        clear: () => { emitter.removeAllListeners(); },
14
    };
15
}

1
events: {
2
    emit(channel, data) { assertActive(); eventBus.emit(channel, data); },
3
    on(channel, handler) {
4
        assertActive();
5
        const unsubscribe = runtime.trackEventBusSubscription(eventBus.on(channel, handler));
6
        if (state === "loading") loadingUnsubscribers.push(unsubscribe);
7
        return unsubscribe;
8
    },
9
},

1
let currentCtx: ExtensionContext | undefined;
2
pi.on("session_start", async (_event, ctx) => { currentCtx = ctx; });
3

4
pi.events.on("my:notification", (data) => {
5
    const { message, from } = data as { message: string; from: string };
6
    currentCtx?.ui.notify(`Event from ${from}: ${message}`, "info");
7
});