@creative-int/pi-tools

Tool-pack contract for pi-mono SDK consumers.

What it is

@creative-int/pi-tools defines the factory shape that products built on @mariozechner/pi-coding-agent use to compose capabilities into a createAgentSession() without source-forking pi-coding-agent.

The package itself is thin on runtime code — it re-exports the pi-mono extension-runtime types under a stable import surface and provides composition helpers. Concrete packs (code, hil, orchestration, annotation) will land here as subpath exports. Existing pi packages (pi-steer, pi-pad, pi-outline) remain separately versioned and export their own factory creators.

Why it exists

Before pi-tools, products that wanted to consume pi extensions had two bad options:

1. Source-fork pi-coding-agent — carries the whole upstream tree, version-locks to a specific release, duplicates maintenance burden.
2. Register tools via customTools — only gets you tool definitions; loses lifecycle hooks, commands, shortcuts, message renderers, state persistence.

pi-tools documents the third path: consume pi's public SDK + extension factory API, load extensions programmatically via DefaultResourceLoader({ extensionFactories: [...] }), and keep the product boundary clean.

Install

pnpm add @creative-int/pi-tools @mariozechner/pi-coding-agent

@mariozechner/pi-coding-agent is a peer dependency.

Usage

Compose factories from pi extensions

import { DefaultResourceLoader, createAgentSession } from "@mariozechner/pi-coding-agent";
import { composePackFactories } from "@creative-int/pi-tools";
import { createSteerFactory } from "@creative-int/pi-steer";
import { createPadFactory } from "@creative-int/pi-pad";
import { createOutlineFactory } from "@creative-int/pi-outline";

const resourceLoader = new DefaultResourceLoader({
  // No filesystem extension discovery — products control their extension set.
  additionalExtensionPaths: [],
  extensionFactories: [
    createSteerFactory(),
    createPadFactory(),
    createOutlineFactory(),
  ],
});

const { session } = await createAgentSession({
  resourceLoader,
});

Conditional composition

import { composePackFactories, whenEnabled } from "@creative-int/pi-tools";
import { createSteerFactory } from "@creative-int/pi-steer";

const factory = composePackFactories(
  createSteerFactory(),
  whenEnabled(structuredMode, () => createHilFactory()),
);

Authoring a pack

import type { PiToolPackFactory } from "@creative-int/pi-tools";

export interface MyPackOptions {
  enabled?: boolean;
  label?: string;
  // product-specific options...
}

export const createMyPackFactory: PiToolPackFactory<MyPackOptions> = (options = {}) => {
  return (pi) => {
    pi.registerTool({ /* ... */ });
    pi.on("session_start", (_ev, ctx) => { /* ... */ });
  };
};

Exports

| specifier | purpose | |---|---| | "@creative-int/pi-tools" | root — contract types + compose re-exports | | "@creative-int/pi-tools/contract" | PiToolPackFactory, PiToolPackOptions, PiToolPackManifest, and re-exports of ExtensionFactory, ExtensionAPI, ExtensionContext, Extension, ToolDefinition, defineTool | | "@creative-int/pi-tools/compose" | composePackFactories(), whenEnabled() |

Design

• Thin re-export layer. We do not redefine pi-mono types; we give them a stable home under @creative-int/pi-tools/contract so factory authors have a consistent import surface.
• Separate packaging from siblings. pi-steer, pi-pad, pi-outline stay separately versioned. pi-tools is their composition substrate, not their umbrella.
• Subpath-ready. Concrete packs (./code, ./hil, ./orchestration, ./annotation) will land as subpath exports as they're extracted from existing product code.

Related

• @mariozechner/pi-coding-agent — the upstream pi SDK
• @creative-int/pi-steer — steering compiler (interviews + handoff synthesis)
• @creative-int/pi-pad — persistent execution memory
• @creative-int/pi-outline — AST-based code structure extension (private lane)

License

MIT