@agentrystudio/omp-extension

Native-only, read-only context selection for Oh My Pi. The extension registers exactly one tool, agentry_select_context, plus a deterministic adoption hook, and lazily loads the matching macOS or GNU Linux optional native package on first selection. The tool is an essential OMP tool so its schema is directly available to the model rather than hidden behind the xd:// discoverable-device transport.

There is no JavaScript fallback, sidecar, daemon, backend abstraction, or filesystem mutation surface. Unsupported platforms fail before native import.

Install

After the extension and native leaves are published, use the OMP version declared by this package's exact peer dependency and install through OMP's plugin manager:

bun install -g @oh-my-pi/[email protected]
omp plugin install @agentrystudio/omp-extension

The install resolves exactly one optional native leaf for the current supported platform. Launch omp from the workspace that should become the read-only capability root.

Repository development validates the equivalent packed local-plugin path with make native-smoke; it does not depend on unpublished registry artifacts.

Adoption modes

Set AGENTRY_ADOPTION before launching OMP:

• preflight (default): for prompts conservatively classified as repository evidence tasks, before_agent_start runs the same native selector/session path as agentry_select_context, injects its result as a custom message, and appends a conditional context-loop instruction. The model consumes the lead first, re-selects only when scope or evidence changes, then verifies exact source. A successful selection with no evidence falls back to guidance.
• preflight_guided: preserves the preflight selection and custom-message injection, then also appends the general context-loop instruction. If preflight fails, times out, or selects no evidence, this mode falls back to guidance without injecting a custom message.
• guided: injects only the context-loop instruction without running native selection.
• off: registers the tool but no adoption hook, preserving the original opt-in behavior.

preflight remains the default because deterministic selection has preserved answer quality while materially reducing latency and tokens. Its conditional instruction avoids an immediate duplicate selection: the model calls agentry_select_context again only after task scope narrows, the working hypothesis changes, or required evidence is missing. preflight_guided remains available for stronger experimental adoption. An unknown value fails safely to off; an unset or empty value uses the default.

The trigger deliberately favors precision over recall. It accepts repository actions with an explicit path/symbol, or with scoped/dense code-artifact signals; evidence questions likewise need a path/symbol or several repository-specific signals. Sparse cases additionally need scoping language such as this, current, or exact. Empty prompts, greetings, creative writing, and general-knowledge questions do not trigger. This avoids paying for or injecting workspace evidence into obviously unrelated turns.

Preflight uses auto selection with the native minimum 10,000-token evidence budget and a 1.5-second extension-side deadline. The native budget bounds the injected file content. In preflight, successful empty selections retain the general context-loop instruction, while errors, malformed responses, and timeouts silently skip injection. In preflight_guided, all of those cases retain the general context-loop instruction. Timeout work is aborted and generation-fenced so it cannot poison the next tool call. Repository contents remain untrusted evidence, not instructions. Embedded callers of createAgentryExtension may override adoptionMode and adoptionTimeoutMs; the installed plugin needs only AGENTRY_ADOPTION.

Direct tool use

The tool remains available in every mode. To request selection explicitly:

Call agentry_select_context to gather the most relevant context for fixing the
authentication refresh timeout, then continue using the selected evidence.

Use the tool as a refinement loop, not as an unconditional duplicate:

1. Consume adequate preflight evidence before making another selection.
2. Call agentry_select_context when no adequate lead exists, before broad exploration.
3. Call it again with refined instructions or paths when task scope narrows, the working hypothesis changes, or selected evidence is incomplete.
4. Verify exact facts in selected files with read and available symbol-aware tools.

The request supports path, extension, and exclusion hints, a token budget from 10,000 through 200,000, and auto, full, or codemap_only selection. OMP owns the agent and session lifecycle; the extension derives its capability root from OMP's current working directory.