@sangyaahub/pi-marg 1.0.7 → 1.0.8

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "PiMarg — a governed development path for Pi Agent and Oh My Pi.",
-    "version": "1.0.7"
+    "version": "1.0.8"
   },
   "plugins": [
     {
       "name": "pi-marg",
       "description": "Intent-led development workflow with live A/B/C/D routing, capability detection, verification, and approval gates.",
       "source": "./",
-      "version": "1.0.7",
+      "version": "1.0.8",
       "author": {
         "name": "Sangyaa",
         "email": "contact@sangyaa.co"

package/CHANGELOG.md

@@ -1,4 +1,10 @@
 # Changelog
+## 1.0.8 — 2026-10-26
+
+- A provider reporting 95% usage pauses while its stage context is kept. The saved high then low backup resumes the stage only when it is a different provider, fits the same stage, and is itself under 95%. Hard quota errors keep the existing failover.
+- Provider lines in the catalog show remaining usage when the host reports `percentUsed`, `percentRemaining`, or `used`/`limit`, and say usage remaining is unknown otherwise.
+- An empty OMP catalog can add the optional Kimi Code preset through the same custom-provider writer. It stores the `KIMI_API_KEY` env var name, writes no API key, and is not needed for a logged-in (OAuth) `kimi-code` provider.
+
 
 ## 1.0.7 — 2026-10-03
 

package/MODEL-SETUP.md

@@ -16,7 +16,7 @@ LIVE AUTHENTICATED CATALOG
    high backup ──► low backup
 ```
 
-If the live catalog is empty, `/pi-marg` offers three actions: sign in with `/login`, add a custom OpenAI-compatible provider, or cancel. The custom path writes `apiKey: ENV_VAR_NAME` into `~/.omp/agent/models.yml` and the secret only into `~/.omp/agent/.env`. Cancelling writes neither file.
+If the live catalog is empty, `/pi-marg` offers four actions: sign in with `/login`, add a custom OpenAI-compatible provider, add the optional Kimi Code preset, or cancel. The custom path writes `apiKey: ENV_VAR_NAME` into `~/.omp/agent/models.yml` and the secret only into `~/.omp/agent/.env`. The Kimi preset uses that same writer with provider id `kimi-code`, display name `Kimi Code`, base URL `https://api.kimi.com/coding/v1`, env var `KIMI_API_KEY`, and the model ids from OMP's Kimi Code provider rule. It does not write an API key. Cancelling writes neither file. A logged-in Kimi provider is listed with every other authenticated provider; the preset is not required for that.
 
 ## Roles
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/sangyaahub/pi-marg/releases"><img alt="Version 1.0.7" src="https://img.shields.io/badge/version-1.0.7-0451F7"></a>
+  <a href="https://github.com/sangyaahub/pi-marg/releases"><img alt="Version 1.0.8" src="https://img.shields.io/badge/version-1.0.8-0451F7"></a>
   <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-C27B1A"></a>
   <a href="https://pi.dev/packages?name=pi-marg"><img alt="Pi package" src="https://img.shields.io/badge/Pi-package-0338A8"></a>
   <a href="https://omp.sh"><img alt="Oh My Pi plugin" src="https://img.shields.io/badge/OMP-plugin-021E5C"></a>
@@ -11,7 +11,7 @@
 
 # PiMarg
 
-**Version 1.0.7 · MIT licensed · Pi Agent + Oh My Pi · by [Sangyaa](https://sangyaa.co)**
+**Version 1.0.8 · MIT licensed · Pi Agent + Oh My Pi · by [Sangyaa](https://sangyaa.co)**
 
 PiMarg turns an ordinary prompt into a governed development path. It identifies the work boundary, selects one engineering method, discovers the models and tools the active runtime really provides, separates thinking from execution, records evidence, and stops before protected actions.
 

package/adapters/omp/extensions/model-router.ts

@@ -10,8 +10,13 @@ import {
   executeAutomaticFailover,
   executeModelRoute,
   failedModelSelector,
+  chooseUsageResume,
+  executeUsageResume,
   findTerminalUsageLimitFailure,
   formatFailoverRecoveryMessage,
+  formatUsagePauseMessage,
+  providerReachedUsagePause,
+  usageSnapshotsFromMessages,
   hasConfiguredFallback,
   modelFailureKey,
   modelToolUsageLimitFailure,
@@ -370,6 +375,29 @@ export default function modelRouter(pi: any) {
 
   pi.on("agent_end", async (event: any, ctx: any) => {
     if (event?.willContinue || event?.isTerminal === false) return;
+    const liveModels = (ctx.models?.list?.() ?? []) as ModelLike[];
+    const current = ctx.models?.current?.() ?? ctx.model;
+    const snapshots = usageSnapshotsFromMessages(event?.messages ?? [], liveModels);
+    const pause = typeof current?.provider === "string" ? providerReachedUsagePause(snapshots, current.provider) : undefined;
+    if (pause && typeof current?.id === "string" && hasConfiguredFallback(state)) {
+      const pausedSelector = `${current.provider}/${current.id}`;
+      const resume = chooseUsageResume(state, snapshots, current.provider);
+      if (resume) {
+        const execution = await executeUsageResume(state, pausedSelector, resume, {
+          runtimeName: "OMP",
+          models: liveModels,
+          hasExternalDevin: hasExternalDevin(pi),
+          activate: (model) => pi.setModel(model),
+          persist: (nextState) => persistRoute(nextState, ctx),
+        });
+        state = execution.state;
+        if (execution.switched) {
+          ctx.ui?.notify?.(`PiMarg paused ${pausedSelector} at ${pause.percentUsed}% usage and resumed on ${execution.switched.selection.selector}.`, "warning");
+          pi.sendUserMessage(formatUsagePauseMessage(pausedSelector, pause, execution.switched.selection.selector), { deliverAs: "aside" });
+          return;
+        }
+      }
+    }
     const failed = findTerminalUsageLimitFailure(event?.messages ?? []);
     const failure = failed
       ? {

package/adapters/omp/extensions/provider-setup.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import {
+  kimiCodeProviderPreset,
   probeModelIds,
   validateCustomProvider,
   writeCustomProvider,
@@ -17,6 +18,7 @@ import { agentDirectory } from "../../../core/user-route";
 const SETUP_ITEMS = [
   "Sign in to a provider",
   "Add a custom OpenAI-compatible provider",
+  "Add the Kimi Code preset",
   "Cancel",
 ] as const;
 
@@ -157,9 +159,34 @@ export async function addCustomProvider(ctx: any, home: string | undefined): Pro
   return { status: "ready", models };
 }
 
+export async function addKimiCodePreset(ctx: any, home: string | undefined): Promise<CatalogSetup> {
+  const preset = kimiCodeProviderPreset();
+  try {
+    const directory = agentDirectory("OMP", home);
+    writeCustomProvider({
+      modelsPath: join(directory, "models.yml"),
+      envPath: join(directory, ".env"),
+    }, preset);
+  } catch (error) {
+    ctx.ui.notify(error instanceof Error ? error.message : "Could not write the Kimi Code preset.", "error");
+    return { status: "cancelled" };
+  }
+  ctx.ui.notify(
+    `Kimi Code was added to models.yml. Set ${preset.envVar} in the environment; the API key was not stored.`,
+    "info",
+  );
+  if (typeof ctx.models?.reload === "function") {
+    await ctx.models.reload();
+  }
+  const models = (ctx.models.list() ?? []) as ModelLike[];
+  if (models.length === 0) return { status: "restart" };
+  return { status: "ready", models };
+}
+
 export async function configureEmptyCatalog(ctx: any, home: string | undefined): Promise<CatalogSetup> {
   const choice = await askItems(ctx, "Model setup", SETUP_ITEMS);
   if (!choice || choice === "Cancel") return { status: "cancelled" };
+  if (choice === "Add the Kimi Code preset") return addKimiCodePreset(ctx, home);
   if (choice === "Sign in to a provider") {
     if (typeof ctx.openLogin === "function") await ctx.openLogin();
     else ctx.ui.notify("Sign in with /login, verify with `omp models`, then run /pi-marg again.", "warning");

package/adapters/pi/extensions/model-router.ts

@@ -7,13 +7,20 @@ import {
   executeAutomaticFailover,
   executeModelRoute,
   failedModelSelector,
+  chooseUsageResume,
+  executeUsageResume,
   findTerminalUsageLimitFailure,
   formatFailoverRecoveryMessage,
+  formatUsagePauseMessage,
+  providerReachedUsagePause,
+  usageSnapshotsFromMessages,
   hasConfiguredFallback,
   modelFailureKey,
   modelToolUsageLimitFailure,
   type ModelLike,
   type ModelRouteParams,
+  type ModelSelection,
+  type ProviderUsageSnapshot,
 } from "../../../core/model-routing";
 import { loadRuntimeRoute, rememberRuntimeRoute } from "../../../core/user-route";
 
@@ -36,6 +43,7 @@ export default function modelRouter(pi: any) {
   let state = emptyModelRouteState();
   let recoveryToken: symbol | undefined;
   let sessionGeneration = 0;
+  let pendingUsagePause: { selector: string; snapshot: ProviderUsageSnapshot; resume: ModelSelection } | undefined;
   let pendingModelFailure: { selector: string; key: string } | undefined;
   let pendingToolFailure: { selector: string; key: string } | undefined;
   const routeHome = (ctx: any) => typeof ctx?.agentHome === "string" ? ctx.agentHome : undefined;
@@ -50,6 +58,7 @@ export default function modelRouter(pi: any) {
   const restore = (_event: unknown, ctx: any) => {
     sessionGeneration += 1;
     recoveryToken = undefined;
+    pendingUsagePause = undefined;
     pendingModelFailure = undefined;
     pendingToolFailure = undefined;
     state = loadRuntimeRoute("Pi", ctx.sessionManager.getBranch(), routeHome(ctx));
@@ -128,6 +137,17 @@ export default function modelRouter(pi: any) {
   };
 
   pi.on("agent_end", (event: any, ctx: any) => {
+    const liveModels = availableModels(ctx);
+    const current = ctx.model as ModelLike | undefined;
+    const snapshots = usageSnapshotsFromMessages(event?.messages ?? [], liveModels);
+    const pause = current?.provider ? providerReachedUsagePause(snapshots, current.provider) : undefined;
+    if (pause && current?.id && hasConfiguredFallback(state)) {
+      const pausedSelector = `${current.provider}/${current.id}`;
+      const resume = chooseUsageResume(state, snapshots, current.provider);
+      if (resume) {
+        pendingUsagePause = { selector: pausedSelector, snapshot: pause, resume };
+      }
+    }
     const failed = findTerminalUsageLimitFailure(event?.messages ?? []);
     pendingModelFailure = failed
       ? { selector: failedModelSelector(failed, ctx.model), key: modelFailureKey(failed) }
@@ -139,6 +159,25 @@ export default function modelRouter(pi: any) {
   });
 
   pi.on("agent_settled", async (_event: unknown, ctx: any) => {
+    const usagePause = pendingUsagePause;
+    pendingUsagePause = undefined;
+    if (usagePause && !pendingModelFailure && !pendingToolFailure) {
+      const execution = await executeUsageResume(state, usagePause.selector, usagePause.resume, {
+        runtimeName: "Pi",
+        models: availableModels(ctx),
+        hasExternalDevin: hasExternalDevin(pi),
+        activate: (model) => pi.setModel(model),
+        persist: (nextState) => persistRoute(nextState, ctx),
+      });
+      state = execution.state;
+      if (execution.switched) {
+        ctx.ui?.notify?.(`PiMarg paused ${usagePause.selector} at ${usagePause.snapshot.percentUsed}% usage and resumed on ${execution.switched.selection.selector}.`, "warning");
+        pi.sendUserMessage(formatUsagePauseMessage(usagePause.selector, usagePause.snapshot, execution.switched.selection.selector), { deliverAs: "followUp" });
+        pendingModelFailure = undefined;
+        pendingToolFailure = undefined;
+        return;
+      }
+    }
     const failure = pendingModelFailure ?? pendingToolFailure;
     pendingModelFailure = undefined;
     pendingToolFailure = undefined;

package/core/model-routing.ts

@@ -3,13 +3,29 @@ export type FallbackLevel = "high" | "low";
 export type CandidateTier = "frontier" | "execution" | "general";
 export type RuntimeName = "OMP" | "Pi";
 
+export interface ModelUsage {
+  percentUsed?: number;
+  percentRemaining?: number;
+  used?: number;
+  limit?: number;
+}
+
 export interface ModelLike {
   provider: string;
   id: string;
   name?: string;
   cost?: Record<string, unknown>;
+  usage?: ModelUsage;
+}
+
+export interface ProviderUsageSnapshot {
+  provider: string;
+  percentUsed: number;
+  percentRemaining: number;
 }
 
+export const USAGE_PAUSE_PERCENT = 95;
+
 export interface ModelCandidate {
   selector: string;
   identity: string;
@@ -158,6 +174,108 @@ export function emptyModelRouteState(): ModelRouteState {
   return { version: 2, selections: {}, fallbacks: {} };
 }
 
+
+function finitePercent(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.min(100, Math.max(0, value));
+}
+
+export function percentUsedFromUsage(usage: ModelUsage | undefined): number | undefined {
+  if (!usage) return undefined;
+  const used = finitePercent(usage.percentUsed);
+  if (used !== undefined) return used;
+  const remaining = finitePercent(usage.percentRemaining);
+  if (remaining !== undefined) return 100 - remaining;
+  if (typeof usage.used === "number" && typeof usage.limit === "number" && usage.limit > 0 && Number.isFinite(usage.used)) {
+    return finitePercent((usage.used / usage.limit) * 100);
+  }
+  return undefined;
+}
+
+export function providerUsageSnapshots(models: readonly ModelLike[]): ProviderUsageSnapshot[] {
+  const byProvider = new Map<string, number>();
+  for (const model of models) {
+    const percentUsed = percentUsedFromUsage(model.usage);
+    if (percentUsed === undefined) continue;
+    const current = byProvider.get(model.provider);
+    if (current === undefined || percentUsed > current) byProvider.set(model.provider, percentUsed);
+  }
+  return [...byProvider.entries()]
+    .map(([provider, percentUsed]) => ({
+      provider,
+      percentUsed,
+      percentRemaining: Math.max(0, 100 - percentUsed),
+    }))
+    .sort((left, right) => left.provider.localeCompare(right.provider));
+}
+
+export function usageSnapshotsFromMessages(
+  messages: readonly unknown[],
+  models: readonly ModelLike[] = [],
+): ProviderUsageSnapshot[] {
+  const reported: ModelLike[] = [...models];
+  for (const message of messages) {
+    const record = asRecord(message);
+    if (!record || typeof record.provider !== "string") continue;
+    const usage = asRecord(record.usage);
+    if (!usage) continue;
+    reported.push({
+      provider: record.provider,
+      id: typeof record.model === "string" ? record.model : "message",
+      usage: {
+        percentUsed: typeof usage.percentUsed === "number" ? usage.percentUsed : undefined,
+        percentRemaining: typeof usage.percentRemaining === "number" ? usage.percentRemaining : undefined,
+        used: typeof usage.used === "number" ? usage.used : undefined,
+        limit: typeof usage.limit === "number" ? usage.limit : undefined,
+      },
+    });
+  }
+  return providerUsageSnapshots(reported);
+}
+
+export function providerReachedUsagePause(
+  snapshots: readonly ProviderUsageSnapshot[],
+  provider: string,
+): ProviderUsageSnapshot | undefined {
+  return snapshots.find((snapshot) => snapshot.provider === provider && snapshot.percentUsed >= USAGE_PAUSE_PERCENT);
+}
+
+function fallbackFitsStage(stage: AutoStage | undefined, selection: ModelSelection): boolean {
+  if (!stage || selection.tier === "general") return true;
+  if (stage === "A" || stage === "C") return selection.tier === "frontier";
+  return selection.tier === "execution";
+}
+
+export function chooseUsageResume(
+  state: ModelRouteState,
+  snapshots: readonly ProviderUsageSnapshot[],
+  pausedProvider: string,
+): ModelSelection | undefined {
+  for (const level of FALLBACK_LEVELS) {
+    const selection = state.fallbacks[level];
+    if (!selection || selection.access !== "runtime-model") continue;
+    if (selection.provider === pausedProvider) continue;
+    if (!fallbackFitsStage(state.activeStage, selection)) continue;
+    const usage = snapshots.find((snapshot) => snapshot.provider === selection.provider);
+    if (usage && usage.percentUsed >= USAGE_PAUSE_PERCENT) continue;
+    return selection;
+  }
+  return undefined;
+}
+
+export function formatUsagePauseMessage(
+  pausedSelector: string,
+  snapshot: ProviderUsageSnapshot,
+  resumeSelector: string,
+): string {
+  return [
+    `[PiMarg usage pause] ${pausedSelector} is at ${snapshot.percentUsed}% usage (${snapshot.percentRemaining}% remaining).`,
+    "Paused and kept the current stage context.",
+    `Resume on ${resumeSelector}, a saved backup of the same stage capability.`,
+  ].join("\n");
+}
+
+
 export function isFallbackLevel(value: unknown): value is FallbackLevel {
   return typeof value === "string" && FALLBACK_LEVELS.includes(value as FallbackLevel);
 }
@@ -471,6 +589,7 @@ export function formatCatalogPresentation(
   catalog: Record<AutoStage, ModelCandidate[]>,
   requiredStages: AutoStage[],
   providerFilter?: string,
+  usage: readonly ProviderUsageSnapshot[] = [],
 ) {
   const notes = catalogNotes(runtimeName, catalog);
   const orderedStages = ascendingStages(requiredStages);
@@ -520,7 +639,9 @@ export function formatCatalogPresentation(
     lines.push("Providers:");
     for (const provider of providers) {
       const marker = providerFilter === provider.name ? " ← selected" : "";
-      lines.push(`  ${provider.index}. ${provider.name} (${provider.count})${marker}`);
+      const snapshot = usage.find((item) => item.provider === provider.name);
+      const remaining = snapshot ? ` — ${snapshot.percentRemaining}% remaining` : " — usage remaining unknown";
+      lines.push(`  ${provider.index}. ${provider.name} (${provider.count})${remaining}${marker}`);
     }
     if (!providerFilter) {
       lines.push("Call catalog again with provider=<name> to list every model for that provider.");
@@ -583,6 +704,45 @@ export function restoreModelRouteState(entries: readonly any[]): ModelRouteState
   return restored;
 }
 
+
+export async function executeUsageResume(
+  currentState: ModelRouteState,
+  pausedSelector: string,
+  selection: ModelSelection,
+  port: ModelRoutePort,
+): Promise<AutomaticFailoverExecution> {
+  const level = (FALLBACK_LEVELS.find((item) => currentState.fallbacks[item]?.selector === selection.selector) ?? "high");
+  const model = port.models.find((item) => `${item.provider}/${item.id}` === selection.selector);
+  if (!model) return { state: currentState, exhausted: true, stateChanged: false };
+  let activated: boolean | void;
+  try {
+    activated = await port.activate(model);
+  } catch {
+    return { state: currentState, exhausted: false, stateChanged: false };
+  }
+  if (activated === false) return { state: currentState, exhausted: false, stateChanged: false };
+  const nextState: ModelRouteState = {
+    ...currentState,
+    version: 2,
+    activeFallback: level,
+    lastFailover: {
+      stage: currentState.activeStage,
+      failedSelector: pausedSelector,
+      fallbackLevel: level,
+      activatedSelector: selection.selector,
+      switchedAt: port.now?.() ?? new Date().toISOString(),
+    },
+  };
+  const persistenceError = persistFailoverState(port, nextState);
+  return {
+    state: nextState,
+    switched: { level, selection },
+    exhausted: false,
+    stateChanged: true,
+    ...(persistenceError ? { persistenceError } : {}),
+  };
+}
+
 export async function executeAutomaticFailover(
   currentState: ModelRouteState,
   failedSelector: string,
@@ -780,7 +940,8 @@ export async function executeModelRoute(
         };
       }
     }
-    const formatted = formatCatalogPresentation(port.runtimeName, catalog, requiredStages, providerFilter);
+    const usage = providerUsageSnapshots(port.models);
+    const formatted = formatCatalogPresentation(port.runtimeName, catalog, requiredStages, providerFilter, usage);
     return {
       state: currentState,
       response: toolResult(formatted.text, {

package/core/provider-config.ts

@@ -15,6 +15,28 @@ export interface ProviderFiles {
   envPath: string;
 }
 
+const KIMI_CODE_MODEL_IDS = [
+  "kimi-for-coding",
+  "k3",
+  "k3-256k",
+  "kimi-for-coding-highspeed",
+  "kimi-k2",
+  "kimi-k2.5",
+  "kimi-k2-turbo-preview",
+] as const;
+
+/** Optional Kimi Code models.yml input. It names the env var and does not carry an API key. */
+export function kimiCodeProviderPreset(): CustomProviderInput {
+  return {
+    providerId: "kimi-code",
+    displayName: "Kimi Code",
+    baseUrl: "https://api.kimi.com/coding/v1",
+    envVar: "KIMI_API_KEY",
+    modelIds: [...KIMI_CODE_MODEL_IDS],
+    allowLocalHttp: false,
+  };
+}
+
 const PROVIDER_ID = /^[a-z0-9_-]+$/;
 const ENV_VAR = /^[A-Z][A-Z0-9_]*$/;
 const MODEL_ID = /^[A-Za-z0-9._:-]+$/;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sangyaahub/pi-marg",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "A governed, model-routed development path for Pi Agent and Oh My Pi.",
   "type": "module",
   "license": "MIT",

package/scripts/install.sh

@@ -71,4 +71,4 @@ if [[ "${runtime}" == "omp" || "${runtime}" == "both" ]]; then
   omp plugin install --scope user pi-marg@pi-marg-marketplace
 fi
 
-echo "PiMarg v1.0.6 installed for ${runtime}. Start a fresh runtime session, then run /pi-marg."
+echo "PiMarg v1.0.8 installed for ${runtime}. Start a fresh runtime session, then run /pi-marg."

package/scripts/validate.sh

@@ -45,7 +45,7 @@ bun -e '
   const packageJson = await Bun.file("package.json").json();
   const marketplace = await Bun.file(".omp-plugin/marketplace.json").json();
   if (packageJson.name !== "@sangyaahub/pi-marg") throw new Error("Unexpected package name");
-  if (packageJson.version !== "1.0.7") throw new Error("package.json must be v1.0.7");
+  if (packageJson.version !== "1.0.8") throw new Error("package.json must be v1.0.8");
   if (packageJson.license !== "MIT") throw new Error("package.json must declare MIT");
   if (packageJson.author !== "Sangyaa") throw new Error("Unexpected package author");
   if (!packageJson.keywords?.includes("pi-package")) throw new Error("Pi catalog keyword is missing");