ns-omp-provider 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: OMP wrapper around `@ngosangns/ns-pi-provider` 0.1.7.
+- Bundles the Pi providers with shims for the missing Pi 1.0 transcript helpers
+  (`getCurrentSystemPrompt` / `getCurrentTools` / `withoutInitialSystemMessage`)
+  and adapts OMP contexts, `fetchDynamicModels`, apiKey syntax, and session events.
+- Providers: `kiro`, `devin`, `grok` (+ `grok-sdk` alias). Opt out of `kiro` with
+  `NS_OMP_PROVIDER_DISABLE=kiro` when `ns-omp-provider-kiro` is already installed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ngosangns
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,23 @@
+ns-omp-provider
+Copyright (c) 2026 ngosangns
+
+This package wraps and redistributes (via bundling) the MIT-licensed
+@ngosangns/ns-pi-provider sources. Upstream NOTICE from that package:
+
+----
+ns-pi-provider
+Copyright (c) 2026 ngosangns
+
+This package adapts patterns and portions of the following MIT-licensed projects:
+
+- pi-kiro-provider (MasuRii) — https://github.com/MasuRii/pi-kiro-provider
+- pi-kiro-api (satiyap) — https://github.com/satiyap/pi-kiro-api
+  (which itself vendors streaming core from pi-kiro under MIT)
+- pi-devin-provider (fadlee) — https://github.com/fadlee/pi-devin-provider
+- pi-grok-sdk (Ankit Chouhan) — https://github.com/ankitchouhan1020/pi-grok-sdk
+- grok-pi — model-cache / CLI bridge patterns
+- Pi custom-provider docs and examples from badlogic/pi-mono / earendil-works
+
+See each upstream LICENSE for full copyright notices. Adaptations are under the
+MIT license of this package; original authorship remains with upstream authors.
+----

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# ns-omp-provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[OMP](https://omp.sh) (oh-my-pi) plugin that exposes the **Kiro**, **Devin**, and
+**Grok** providers from [`@ngosangns/ns-pi-provider`](https://github.com/ngosangns/ns-pi-provider).
+
+`ns-pi-provider` targets Pi 1.0. OMP is a Pi fork whose extension API is close
+but not identical — this package is the adapter. It does **not** modify
+`ns-pi-provider`; the Pi sources are bundled at build time with a small
+compat layer.
+
+| Provider | Auth | Notes |
+|----------|------|-------|
+| `kiro` | OAuth (`/login kiro`) + `KIRO_API_KEY` / SSO cache | Overlaps with [`ns-omp-provider-kiro`](https://www.npmjs.com/package/ns-omp-provider-kiro) — see below |
+| `devin` | OAuth (`/login devin`) + `credentials.toml` / env | Swe-2 catalog when authenticated |
+| `grok` (+ `grok-sdk` alias) | Local `grok` CLI / `~/.grok` / `XAI_API_KEY` | Commands: `/grok status \| models \| refresh` |
+
+Shared command: `/ns-pi status | refresh [all\|kiro\|devin\|grok]`.
+
+## Install
+
+```bash
+# from npm (after first publish)
+omp plugin install ns-omp-provider
+
+# from git
+omp plugin install git:github.com/ngosangns/ns-omp-provider
+
+# local link (dev)
+omp plugin link ~/Github/ngosangns/ns-omp-provider
+
+# one-shot without installing
+omp -e ./dist/index.js ...
+# or: omp models --no-extensions -e ./dist/index.js
+```
+
+Then `/login kiro` or `/login devin` as needed. Grok uses the local `grok`
+CLI / `~/.grok` auth (or `XAI_API_KEY`).
+
+### Avoiding a duplicate `kiro` provider
+
+If you already use [`ns-omp-provider-kiro`](https://www.npmjs.com/package/ns-omp-provider-kiro),
+disable this package's kiro registration:
+
+```bash
+# in the shell that launches omp, or via your shell profile / omp env
+export NS_OMP_PROVIDER_DISABLE=kiro
+```
+
+Or allow-list only what you want: `NS_OMP_PROVIDERS=devin,grok`.
+
+## How the wrapper works
+
+1. **Build-time** — esbuild bundles `@ngosangns/ns-pi-provider` into
+   `dist/index.js`, rewriting `@earendil-works/pi-ai*` imports onto
+   `src/compat/` (OMP's `@oh-my-pi/pi-ai` plus Pi 1.0 transcript helpers that
+   OMP does not ship: `getCurrentSystemPrompt`, `getCurrentTools`,
+   `withoutInitialSystemMessage`).
+2. **Runtime** — the OMP `ExtensionAPI` is wrapped so that:
+   - OMP contexts (`systemPrompt: string[]`, `developer` messages) become the
+     Pi shape (`systemPrompt: string`, no developer role) before
+     `streamSimple`.
+   - Pi's `refreshModels({credential, signal, allowNetwork})` is exposed as
+     OMP's `fetchDynamicModels(apiKey)`.
+   - Pi `$ENV` / `$$` apiKey syntax is translated to OMP's.
+   - Unsupported events (`session_info_changed`) are no-ops; OMP's
+     `session_switch` / `session_branch` also fire Pi's `session_start`
+     handlers (OMP only emits `session_start` once at startup).
+
+`ns-pi-provider` itself is unchanged.
+
+## Known limitations
+
+- **`session_info_changed`** — OMP has no equivalent; the grok handler is a
+  documented no-op (name changes do not re-key the agent pool).
+- **Duplicate `kiro`** — see `NS_OMP_PROVIDER_DISABLE` above.
+- **Unauthenticated catalogs** — without credentials, OMP may hide a provider's
+  models from `omp models` even though the provider is registered. After
+  `/login` (or with CLI creds present) the live catalog, including Devin
+  `swe-2-*`, appears via `fetchDynamicModels`.
+- **Upstream pin** — this release bundles `@ngosangns/ns-pi-provider@0.1.7`.
+  Bumping it is a deliberate change (rebuild + retest).
+
+## Development
+
+```bash
+npm install
+npm test          # hermetic unit + bundle load tests
+npm run typecheck
+npm run build
+npm run smoke     # optional: real `omp models -e dist/index.js` under a temp HOME
+```
+
+Requires Node ≥ 20. The smoke script needs `omp` on `PATH` and does not touch
+your real `~/.omp`.
+
+## Publish
+
+Push a tag matching `package.json` (e.g. `v0.1.0`) to run
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml), which
+publishes with **provenance** from a GitHub-hosted runner:
+
+```bash
+# bump "version" in package.json first, then
+npm run check
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+Auth, in the order npm tries it:
+
+1. **Trusted publishing (OIDC)**, if a trusted publisher is attached to the
+   package. npm only allows that once the package exists:
+   ```bash
+   npm trust github ns-omp-provider --file publish.yml \
+     --repo ngosangns/ns-omp-provider --allow-publish
+   ```
+2. **`NPM_TOKEN` repository secret** (currently set): a granular npm token with
+   package write and "bypass 2FA", passed to npm as `NODE_AUTH_TOKEN`. This
+   covers the first publish. After trusted publishing is configured the secret
+   can be removed (`gh secret delete NPM_TOKEN --repo ngosangns/ns-omp-provider`).
+
+Manual publish from a logged-in machine still works:
+`npm run check && npm publish --access public`.

package/dist/adapter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Runtime adapters between ns-pi-provider (written for Pi 1.0) and OMP.
+ *
+ * Pi 1.0 and OMP (oh-my-pi) share the extension surface ns-pi-provider uses
+ * (registerProvider / registerCommand / on / ctx.ui / ctx.modelRegistry), but
+ * differ in a few contracts:
+ *
+ *  - Context: OMP passes `systemPrompt?: string[]` and may include
+ *    `role: "developer"` messages; Pi providers expect `systemPrompt?: string`
+ *    and only user / assistant / toolResult (/ system) roles.
+ *  - Model refresh: Pi calls `refreshModels({ credential, signal, allowNetwork })`;
+ *    OMP calls `fetchDynamicModels(apiKey)`.
+ *  - apiKey config: Pi resolves `$ENV` and unescapes `$$`; OMP treats the value
+ *    as an exact env-var name, `!command`, or a literal.
+ *  - Events: Pi 1.0 fires `session_start` on every session (new/resume/switch)
+ *    and has `session_info_changed`; OMP fires `session_start` once at startup,
+ *    `session_switch` / `session_branch` afterwards, and has no
+ *    `session_info_changed`.
+ */
+export type AnyRecord = Record<string, unknown>;
+export interface OmpLikeContext {
+    systemPrompt?: string | string[];
+    messages: Array<{
+        role: string;
+        [key: string]: unknown;
+    }>;
+    tools?: unknown[];
+    [key: string]: unknown;
+}
+/** Events ns-pi-provider subscribes to that OMP never emits. */
+export declare const UNSUPPORTED_EVENTS: ReadonlySet<string>;
+/** OMP events that correspond to Pi 1.0's `session_start` (which OMP only fires at startup). */
+export declare const SESSION_START_ALIASES: readonly string[];
+/** Default timeout for a `fetchDynamicModels` call (OMP also bounds it). */
+export declare const DYNAMIC_MODELS_TIMEOUT_MS = 30000;
+/**
+ * Convert an OMP stream context into the Pi 1.0 shape the providers expect.
+ * Pi-shaped contexts (string systemPrompt, no developer messages) pass through
+ * untouched (same object), so behaviour under Pi-style callers is unchanged.
+ */
+export declare function toPiContext<T extends OmpLikeContext>(context: T): T;
+/**
+ * Translate a Pi apiKey config value into OMP's syntax.
+ *  - `$NAME`  → `NAME` when that env var is set (OMP reads it live); dropped otherwise,
+ *               so OMP falls back to /login credentials instead of sending the
+ *               literal string "NAME" as a key.
+ *  - `$$`     → `$` (Pi's escape for literal dollars).
+ *  - anything else (literals, `!command`) passes through.
+ */
+export declare function toOmpApiKey(value: unknown, env?: NodeJS.ProcessEnv): string | undefined;
+type PiRefreshModels = (args: {
+    credential?: {
+        type: string;
+        key?: string;
+        access?: string;
+    };
+    signal: AbortSignal;
+    allowNetwork: boolean;
+}) => unknown;
+/** Build OMP's `fetchDynamicModels(apiKey)` from a Pi `refreshModels` hook. */
+export declare function toFetchDynamicModels(refreshModels: PiRefreshModels, timeoutMs?: number): (apiKey: string | undefined) => Promise<unknown[]>;
+/** Adapt one Pi `registerProvider` config to OMP's `ProviderConfig`. */
+export declare function adaptProviderConfig(config: AnyRecord, env?: NodeJS.ProcessEnv): AnyRecord;
+export interface WrapOptions {
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Wrap OMP's ExtensionAPI so ns-pi-provider's Pi-targeted registration code
+ * runs unchanged: provider configs are adapted, unsupported events are dropped,
+ * and `session_start` handlers also run on OMP's session switch/branch events.
+ * Every other member is forwarded (methods bound to the real API object).
+ */
+export declare function wrapExtensionApi<T extends object>(pi: T, options?: WrapOptions): T;
+export {};

package/dist/compat/cost.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `calculateCost` as exported by @earendil-works/pi-ai 1.0. OMP moved it to
+ * `@oh-my-pi/pi-catalog/models`; reimplemented here (pure) so the bundle does
+ * not depend on a second OMP package or its legacy shim.
+ */
+interface CostRates {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+interface CostTier extends CostRates {
+    inputTokensAbove: number;
+}
+export interface CostModel {
+    cost?: Partial<CostRates> & {
+        tiers?: CostTier[];
+    };
+}
+export interface CostUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cacheWrite1h?: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    [key: string]: unknown;
+}
+export declare function calculateCost(model: CostModel, usage: CostUsage): CostUsage["cost"];
+export {};

package/dist/compat/pi-ai-oauth.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build-time replacement for `@earendil-works/pi-ai/oauth`.
+ *
+ * ns-pi-provider's kiro module calls `registerOAuthProvider` best-effort so
+ * Pi's `/login` lists it. On OMP, `pi.registerProvider(..., { oauth })`
+ * already registers the OAuth provider (scoped to this extension's source id,
+ * so it is cleaned up on reload). A second, unscoped global registration
+ * would outlive the extension, so this is intentionally a no-op.
+ */
+export declare function registerOAuthProvider(_provider: unknown): void;

package/dist/compat/pi-ai.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Build-time replacement for `@earendil-works/pi-ai` and
+ * `@earendil-works/pi-ai/compat` inside the bundled ns-pi-provider sources.
+ *
+ * Deliberately NOT `export *`: listing every runtime symbol lets esbuild fail
+ * the build when ns-pi-provider starts importing something OMP lacks, instead
+ * of OMP failing at extension load ("Export named ... not found").
+ */
+export { createAssistantMessageEventStream } from "@oh-my-pi/pi-ai";
+export { calculateCost } from "./cost.js";
+export { getCurrentSystemPrompt, getCurrentTools, withoutInitialSystemMessage } from "./transcript.js";

package/dist/compat/pi-coding-agent.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Build-time replacement for `@earendil-works/pi-coding-agent`.
+ * ns-pi-provider only imports types from it; an empty module makes esbuild
+ * fail loudly if a runtime import ever appears.
+ */
+export {};

package/dist/compat/transcript.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pi 1.0 transcript helpers that OMP's pi-ai does not ship.
+ *
+ * Pi 1.0 folds the system prompt and tool set into `role: "system"` messages
+ * (`toolsAdded` / `toolsRemoved` deltas) and providers read them back with
+ * these helpers. OMP keeps them on `context.systemPrompt` / `context.tools`
+ * and never puts system messages in the transcript, so on OMP these resolve
+ * to "" / [] / the messages unchanged — and the providers fall through to
+ * the (normalized) `context.systemPrompt` / `context.tools` they check first.
+ *
+ * Semantics mirror @earendil-works/pi-ai 1.0 `dist/utils/transcript.js`.
+ */
+export interface ToolLike {
+    name: string;
+    [key: string]: unknown;
+}
+export interface MessageLike {
+    role: string;
+    content?: unknown;
+    toolsAdded?: ToolLike[];
+    toolsRemoved?: Array<{
+        name: string;
+    }>;
+    sections?: Record<string, string | null>;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+/** Drop the leading system message for APIs that carry the prompt outside the message list. */
+export declare function withoutInitialSystemMessage<T extends {
+    role: string;
+}>(messages: T[]): T[];
+/** Resolve the tools available after applying every transcript delta in order. */
+export declare function getCurrentTools<T = ToolLike>(messages: ReadonlyArray<{
+    role: string;
+}>): T[];
+/**
+ * Render the current system prompt after replaying every system message:
+ * base `content` blocks are concatenated, named `sections` are patched in
+ * order (null deletes) and appended after the base prompt.
+ */
+export declare function getCurrentSystemPrompt(messages: ReadonlyArray<{
+    role: string;
+}>): string;

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+/** Which wrapped providers to register, from the environment. */
+export declare const PROVIDER_KEYS: readonly ["kiro", "devin", "grok"];
+export type ProviderKey = (typeof PROVIDER_KEYS)[number];
+export type ProviderSelection = Record<ProviderKey, boolean>;
+/**
+ * - `NS_OMP_PROVIDERS=devin,grok` — allow-list (only these are registered).
+ * - `NS_OMP_PROVIDER_DISABLE=kiro` — deny-list, applied after the allow-list.
+ * Default: all three.
+ */
+export declare function resolveProviderSelection(env?: NodeJS.ProcessEnv): ProviderSelection;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { adaptProviderConfig, toPiContext, toOmpApiKey, toFetchDynamicModels, wrapExtensionApi } from "./adapter.js";
+export { resolveProviderSelection } from "./config.js";
+export default function nsOmpProvider(pi: object): Promise<void>;