pi-deferred-context-engine

For fat Pi installs: keep a small active tool set, search for the rest, promote for one run, then reset.

Needs Pi 0.82+ and Node 22+. Install after other tool-owning extensions.

Install

pi install npm:pi-deferred-context-engine

From a clone:

pi install ./packages/pi-deferred-context-engine

/deferred status
/deferred audit

Config: ~/.pi/agent/deferred-tools.json or PI_DEFERRED_TOOLS_CONFIG.

What it does

• Defers tool schemas (and their prompt snippets) that are not pinned
• Strips the global skill index from the turn prompt; search_tools can load a matching skill
• Drops byte-identical duplicate AGENTS.md blocks (keeps distinct files)
• After agent_settled, run-scoped promotions clear (default)

Hard spine is always search_tools. Defaults also pin stock tools (read, bash, edit, write, grep, find, ls) and papercuts if that package is installed.

Tools

Tool	Default	Role
search_tools	active	Search by task intent; promote tools / load best skill
list_capabilities	deferred	Catalog
promote_tools	deferred	Activate by exact name
demote_tools	deferred	Drop active tools that are not demote-guarded

Commands

/deferred status | audit | apply | reload | config

Config sketch

alwaysActive pins (force active on sync).
neverDefer guards demote (never auto-deferred; demote refused).
Same name can be in one, both, or neither.

{
  "replaceAlwaysActive": true,
  "replaceNeverDefer": true,
  "alwaysActive": ["my_critical_tool"],
  "neverDefer": ["my_critical_tool"]
}

Setting	Default	Notes
enabled	true	false turns deferral off and restores full tool set
deferByDefault	true	Defer unpinned tools
deferSkills	true	Skill index via search
deduplicateContext	true	Identical context blocks once
promotionLifetime	run	session keeps promotions across settles
maxSearchResults	3	Cap per search
maxSkillBytes	65536	Skill body size limit
deferredPrefixes	["mcp_"]	Prefix defer
activeSkills	[]	Skills kept in prompt
toolPriority	[]	Ordered soft routing signal for active tools. User list replaces defaults wholesale.
compactSchemas	{ enabled: false }	Tiered schema disclosure for active tools (see below)

Lists merge with defaults unless replaceAlwaysActive / replaceNeverDefer is true. After config edits: /deferred reload. After package order changes: Pi /reload.

Tool priority

When DCE is enabled, toolPriority controls the order sent to Pi:

{
  "toolPriority": ["preferred_reader", "general_shell"]
}

1. Listed tools that are active appear first, in configured order.
2. Every other active tool follows in its existing relative order.

The order is applied at startup, reload/apply, before each agent run, and after dynamic promotion. Promotions stay additive: DCE keeps every active tool and inserts newly promoted tools at their configured position.

toolPriority does not activate or defer a tool by itself. An inactive entry takes its position when a pin or promotion activates it. Unknown names are ignored. When DCE is disabled, it restores registration order and does not apply priority.

Missing alwaysActive pins are reported as missingPins in /deferred status.

See config.example.json in the package.

Compact schemas (tiered disclosure)

With many tools active, parameter-schema prose dominates the request payload. compactSchemas keeps every active tool's structural schema (types, enums, required) while pruning long prose in place:

{
  "compactSchemas": {
    "enabled": true,
    "maxParamDescriptionChars": 160,
    "keepFull": ["my_complex_tool"]
  }
}

• Property descriptions longer than maxParamDescriptionChars are truncated at a sentence boundary; examples and $comment are dropped.
• Promoting a tool (search_tools / promote_tools) restores its original schema byte-exact; demotion re-compacts it. Disabling the engine restores everything.
• keepFull names (plus the spine) are never compacted.
• /deferred status reports compaction: { compactedTools, savedBytes }.

Gotchas

• Not an auto-router. Agent must call search_tools with intent.
• Empty replaceAlwaysActive: true leaves only search_tools pinned -- pin your real core tools.
• Skill index strip matches Pi stock (and one compressed form); other rewriters may leave the index in the prompt.
• Skills come only from paths Pi already trusted; treat them as trusted content.

More: residual risks.

License

MIT.