@robhowley/pi-openrouter 0.10.0 → 0.11.0

package/extensions/openrouter/account-types.ts

@@ -13,7 +13,7 @@ export type KeyStatus =
 export type BYOKStatus = 'incl' | 'excl' | '?';
 
 /** Reset cadence for key limits */
-export type ResetCadence = 'monthly' | 'daily' | 'never' | 'partial';
+export type ResetCadence = 'monthly' | 'weekly' | 'daily' | 'never' | 'partial';
 
 /** Information about a single OpenRouter key */
 export interface KeyInfo {
@@ -23,14 +23,21 @@ export interface KeyInfo {
   used: number; // Current usage (currency)
   limit?: number; // Key cap (optional)
   remaining?: number; // limit - used
-  resetCadence: ResetCadence; // monthly, daily, never, or partial
+  resetCadence: ResetCadence; // monthly, weekly, daily, never, or partial
   byok: BYOKStatus; // incl (true), excl (false), ? (unavailable)
-  hash: string; // Key hash for identification
+  hash?: string; // Trusted key hash for identification/mutation when available
   disabled: boolean; // Whether key is disabled
   workspaceName: string; // Name of the workspace this key belongs to
   spend: number; // Spend associated with this key (in USD)
 }
 
+/** How the currently authenticated key relates to listed inventory rows. */
+export type CurrentKeyRelation =
+  | { kind: 'inventory-match'; hash: string; label: string }
+  | { kind: 'external-provisioning'; label: string }
+  | { kind: 'ambiguous-label'; label: string; matchingHashes: string[] }
+  | { kind: 'unresolved'; reason: string; label?: string };
+
 /** Rollup status for the entire account */
 export type RollupStatus =
   | { status: 'unavailable'; message?: never }

package/extensions/openrouter/api-key-commands.ts

@@ -0,0 +1,287 @@
+import { createApiKey, setApiKeyDisabled } from './account-client.js';
+
+export interface HandlerResult {
+  success: boolean;
+  message: string;
+  /** Create-only one-time secret. The command router must render this outside notify/log paths. */
+  secret?: string;
+}
+
+export interface ParsedApiKeyCreateArgs {
+  name: string;
+  limit?: number | null;
+  limitReset?: 'daily' | 'weekly' | 'monthly' | null;
+  includeByokInLimit?: boolean;
+  workspaceId?: string;
+  expiresAt?: Date;
+}
+
+const API_KEY_CREATE_USAGE =
+  'Usage: /openrouter api-key-create <name> [limit=<usd|none>] [reset=<daily|weekly|monthly|none>] [byok=<incl|excl>] [workspace=<id>] [expires=<UTC ISO>]';
+const API_KEY_DISABLE_USAGE = 'Usage: /openrouter api-key-disable <hash>';
+const API_KEY_ENABLE_USAGE = 'Usage: /openrouter api-key-enable <hash>';
+
+const ALLOWED_RESET_VALUES = new Set(['daily', 'weekly', 'monthly', 'none']);
+const ALLOWED_BYOK_VALUES = new Set(['incl', 'excl']);
+
+export function isUtcIsoTimestamp(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value)) {
+    return false;
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return false;
+  }
+
+  const canonical = parsed.toISOString();
+  return value === canonical || value === canonical.replace('.000Z', 'Z');
+}
+
+function tokenizeArgs(
+  args: string,
+): { ok: true; value: string[] } | { ok: false; message: string } {
+  const tokens: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | null = null;
+
+  for (const char of args.trim()) {
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (quote) {
+    return {
+      ok: false,
+      message: `Unterminated quoted string in arguments.\n${API_KEY_CREATE_USAGE}`,
+    };
+  }
+
+  if (current) {
+    tokens.push(current);
+  }
+
+  return { ok: true, value: tokens };
+}
+
+export function parseApiKeyCreateArgs(
+  args: string,
+): { ok: true; value: ParsedApiKeyCreateArgs } | { ok: false; message: string } {
+  const tokenized = tokenizeArgs(args);
+  if (!tokenized.ok) {
+    return { ok: false, message: tokenized.message };
+  }
+
+  const parts = tokenized.value;
+  const name = parts[0];
+
+  if (!name || name.includes('=')) {
+    return { ok: false, message: API_KEY_CREATE_USAGE };
+  }
+
+  const parsed: ParsedApiKeyCreateArgs = { name };
+
+  for (const token of parts.slice(1)) {
+    const separatorIndex = token.indexOf('=');
+    if (separatorIndex === -1) {
+      return {
+        ok: false,
+        message: `Invalid option: "${token}"\nExpected key=value options after the key name.\n${API_KEY_CREATE_USAGE}`,
+      };
+    }
+
+    const key = token.slice(0, separatorIndex).trim();
+    const rawValue = token.slice(separatorIndex + 1).trim();
+
+    switch (key) {
+      case 'limit': {
+        if (rawValue === 'none') {
+          parsed.limit = null;
+          break;
+        }
+
+        if (rawValue === '') {
+          return {
+            ok: false,
+            message: `Invalid limit value: "${rawValue}"\nExpected a non-negative USD amount or 'none'.`,
+          };
+        }
+
+        const limit = Number(rawValue);
+        if (!Number.isFinite(limit) || limit < 0) {
+          return {
+            ok: false,
+            message: `Invalid limit value: "${rawValue}"\nExpected a non-negative USD amount or 'none'.`,
+          };
+        }
+
+        parsed.limit = limit;
+        break;
+      }
+      case 'reset': {
+        if (!ALLOWED_RESET_VALUES.has(rawValue)) {
+          return {
+            ok: false,
+            message: `Invalid reset value: "${rawValue}"\nAllowed values: daily, weekly, monthly, none.`,
+          };
+        }
+
+        parsed.limitReset =
+          rawValue === 'none' ? null : (rawValue as 'daily' | 'weekly' | 'monthly');
+        break;
+      }
+      case 'byok': {
+        if (!ALLOWED_BYOK_VALUES.has(rawValue)) {
+          return {
+            ok: false,
+            message: `Invalid byok value: "${rawValue}"\nAllowed values: incl, excl.`,
+          };
+        }
+
+        parsed.includeByokInLimit = rawValue === 'incl';
+        break;
+      }
+      case 'workspace': {
+        if (!rawValue) {
+          return {
+            ok: false,
+            message: 'Invalid workspace value: workspace id cannot be empty.',
+          };
+        }
+
+        parsed.workspaceId = rawValue;
+        break;
+      }
+      case 'expires': {
+        if (!isUtcIsoTimestamp(rawValue)) {
+          return {
+            ok: false,
+            message: `Invalid expires value: "${rawValue}"\nExpected an ISO 8601 UTC timestamp ending in Z, for example 2026-06-01T00:00:00Z.`,
+          };
+        }
+
+        parsed.expiresAt = new Date(rawValue);
+        break;
+      }
+      default:
+        return {
+          ok: false,
+          message: `Unknown option: "${key}"\nAllowed options: limit, reset, byok, workspace, expires.\n${API_KEY_CREATE_USAGE}`,
+        };
+    }
+  }
+
+  return { ok: true, value: parsed };
+}
+
+export async function handleApiKeyCreate(args: string): Promise<HandlerResult> {
+  const parsed = parseApiKeyCreateArgs(args);
+  if (!parsed.ok) {
+    return {
+      success: false,
+      message: parsed.message,
+    };
+  }
+
+  try {
+    const created = await createApiKey(parsed.value);
+    const status = created.keyState.disabled ? 'disabled' : 'enabled';
+
+    return {
+      success: true,
+      message: [
+        'OpenRouter API key created',
+        `Name: ${created.keyState.name}`,
+        `Status: ${status}`,
+        'Use /openrouter account to inspect or toggle the key.',
+        'Secret shown in secure overlay; store it now.',
+        'Warning: This secret cannot be recovered and was not written or cached locally.',
+      ].join('\n'),
+      secret: created.key,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: getErrorMessage(error),
+    };
+  }
+}
+
+export async function handleApiKeyDisable(args: string): Promise<HandlerResult> {
+  return handleApiKeyToggle(args, true);
+}
+
+export async function handleApiKeyEnable(args: string): Promise<HandlerResult> {
+  return handleApiKeyToggle(args, false);
+}
+
+async function handleApiKeyToggle(args: string, disabled: boolean): Promise<HandlerResult> {
+  const tokenized = tokenizeArgs(args);
+  if (!tokenized.ok) {
+    return {
+      success: false,
+      message: disabled ? API_KEY_DISABLE_USAGE : API_KEY_ENABLE_USAGE,
+    };
+  }
+
+  const parts = tokenized.value;
+  const hash = parts[0];
+
+  if (!hash || parts.length !== 1) {
+    return {
+      success: false,
+      message: disabled ? API_KEY_DISABLE_USAGE : API_KEY_ENABLE_USAGE,
+    };
+  }
+
+  try {
+    const keyInfo = await setApiKeyDisabled(hash, disabled);
+    return {
+      success: true,
+      message: [
+        `OpenRouter API key ${disabled ? 'disabled' : 'enabled'}`,
+        `Name: ${keyInfo.name}`,
+        `Status: ${keyInfo.disabled ? 'disabled' : 'enabled'}`,
+        'Run /openrouter account to verify.',
+      ].join('\n'),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: getToggleErrorMessage(error, disabled),
+    };
+  }
+}
+
+function getToggleErrorMessage(error: unknown, disabled: boolean): string {
+  const message = getErrorMessage(error);
+  if (/OPENROUTER_MANAGEMENT_KEY/i.test(message)) {
+    return message;
+  }
+  return `Failed to ${disabled ? 'disable' : 'enable'} OpenRouter API key. Check the key identifier and management-key permissions.`;
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/extensions/openrouter/commands.ts

@@ -12,8 +12,13 @@ import { UsageOverlayComponent } from './overlay.js';
 import { getCurrentSessionId } from './hooks.js';
 import { AccountOverlayComponent } from './account-overlay.js';
 import { computeRollupStatus, sortKeys } from './account-format.js';
-import { getAllKeys, getCurrentKey, getAccountCredits } from './account-client.js';
-import type { KeyInfo, RollupStatus } from './account-types.js';
+import {
+  getAllKeys,
+  getCurrentKey,
+  resolveCurrentKeyRelation,
+  getAccountCredits,
+} from './account-client.js';
+import type { CurrentKeyRelation, KeyInfo, RollupStatus } from './account-types.js';
 import {
   syncModels,
   getSyncState,
@@ -30,6 +35,8 @@ import {
   handleModelOverrideClear,
   handleModelOverrideList,
 } from './models/override-commands.js';
+import type { HandlerResult } from './api-key-commands.js';
+import { handleApiKeyCreate, handleApiKeyDisable, handleApiKeyEnable } from './api-key-commands.js';
 
 export const OPENROUTER_SUBCOMMANDS = [
   'usage',
@@ -40,6 +47,7 @@ export const OPENROUTER_SUBCOMMANDS = [
   'model-override-set',
   'model-override-clear',
   'model-override-list',
+  'api-key-create',
 ] as const;
 
 export function registerOpenRouterCommands(pi: Pick<ExtensionAPI, 'registerCommand'>): void {
@@ -70,7 +78,7 @@ export function registerOpenRouterCommands(pi: Pick<ExtensionAPI, 'registerComma
   });
 
   pi.registerCommand('openrouter', {
-    description: 'OpenRouter commands: usage, account, session, models-sync, models-status',
+    description: `OpenRouter commands: ${OPENROUTER_SUBCOMMANDS.join(', ')}`,
     getArgumentCompletions: getOpenRouterSubcommandCompletions,
     handler: async (args, ctx) => {
       await handleOpenRouterCommand(args, ctx);
@@ -122,6 +130,19 @@ async function handleOpenRouterCommand(args: string, ctx: ExtensionContext): Pro
       await handleModelOverrideListCommand(subcommandArgs, ctx);
       break;
     }
+    case 'api-key-create': {
+      await handleApiKeyCreateCommand(subcommandArgs, ctx);
+      break;
+    }
+    // Back-compat only: hidden from public help/completions in favor of /openrouter account toggle UX.
+    case 'api-key-disable': {
+      await handleApiKeyDisableCommand(subcommandArgs, ctx);
+      break;
+    }
+    case 'api-key-enable': {
+      await handleApiKeyEnableCommand(subcommandArgs, ctx);
+      break;
+    }
     default: {
       notifyUnknownSubcommand(ctx);
       break;
@@ -294,6 +315,77 @@ async function handleModelOverrideListCommand(
   }
 }
 
+async function handleApiKeyCreateCommand(
+  subcommandArgs: string,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const result = await handleApiKeyCreate(subcommandArgs);
+  if (!result.success) {
+    ctx.ui.notify(result.message, 'error');
+    return;
+  }
+
+  if (result.secret) {
+    await showApiKeySecretOverlay(ctx, result);
+  }
+  ctx.ui.notify(result.message, 'info');
+}
+
+async function handleApiKeyDisableCommand(
+  subcommandArgs: string,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const result = await handleApiKeyDisable(subcommandArgs);
+  ctx.ui.notify(result.message, result.success ? 'info' : 'error');
+}
+
+async function handleApiKeyEnableCommand(
+  subcommandArgs: string,
+  ctx: ExtensionContext,
+): Promise<void> {
+  const result = await handleApiKeyEnable(subcommandArgs);
+  ctx.ui.notify(result.message, result.success ? 'info' : 'error');
+}
+
+async function showApiKeySecretOverlay(
+  ctx: ExtensionContext,
+  result: HandlerResult,
+): Promise<void> {
+  if (!result.secret) return;
+
+  const lines = [
+    'OpenRouter API key created',
+    '',
+    ...result.message
+      .split('\n')
+      .filter((line) => line !== 'OpenRouter API key created' && !line.startsWith('Secret shown')),
+    '',
+    'Secret (store now; shown once):',
+    result.secret,
+    '',
+    'Press any key to close.',
+  ];
+
+  await ctx.ui.custom<void>(
+    (_tui, theme, _keybindings, done) => ({
+      handleInput: () => {
+        done();
+      },
+      render: (_width: number) =>
+        lines.map((line, index) => (index === 0 ? theme.bold(line) : line)),
+      invalidate: () => {},
+      dispose: () => {},
+      wantsKeyRelease: false,
+    }),
+    {
+      overlay: true,
+      overlayOptions: {
+        width: 120,
+      },
+    },
+  );
+}
+
 function notifyUnknownSubcommand(ctx: ExtensionContext): void {
   const message = `Available subcommands: ${OPENROUTER_SUBCOMMANDS.join(', ')}`;
   ctx.ui.notify(`OpenRouter subcommands\n${message}`, 'error');
@@ -336,13 +428,21 @@ async function showAccountOverlay(ctx: ExtensionContext) {
   let error: string | null = null;
   let keyInfo: KeyInfo[] | null = null;
   let credits: number | null = null;
+  let canManageKeys = false;
+  let currentKeyRelation: CurrentKeyRelation | undefined;
 
   try {
-    const allKeys = await getAllKeys();
+    const keyInventory = await getAllKeys();
+    canManageKeys = keyInventory.canManageKeys;
 
-    if (allKeys && allKeys.length > 0) {
-      keyInfo = allKeys;
-    } else {
+    if (keyInventory.keys.length > 0) {
+      keyInfo = keyInventory.keys;
+      try {
+        currentKeyRelation = await resolveCurrentKeyRelation(keyInfo);
+      } catch {
+        // Safe gating: disabling stays blocked until current-key identity is available.
+      }
+    } else if (keyInventory.degradedReason === 'management-unavailable') {
       error = 'Key list unavailable - set OPENROUTER_MANAGEMENT_KEY for full key inventory.';
 
       try {
@@ -360,12 +460,12 @@ async function showAccountOverlay(ctx: ExtensionContext) {
 
     credits = await getAccountCredits();
 
-    if (!keyInfo && !credits) {
+    if (!keyInfo && !credits && keyInventory.degradedReason === 'missing-api-key') {
       error =
         'OpenRouter API key not found. Set OPENROUTER_MANAGEMENT_KEY (preferred) or OPENROUTER_API_KEY to use /openrouter-account.';
     }
 
-    if (!keyInfo && credits !== null) {
+    if (!keyInfo && credits !== null && keyInventory.degradedReason === 'management-unavailable') {
       error =
         error ||
         'Key information unavailable. Set OPENROUTER_MANAGEMENT_KEY for full key inventory.';
@@ -379,7 +479,15 @@ async function showAccountOverlay(ctx: ExtensionContext) {
       keyInfo = sortKeys(keyInfo);
     }
 
-    await showAccountOverlayComponent(ctx, keyInfo, credits, rollupStatus, error);
+    await showAccountOverlayComponent(
+      ctx,
+      keyInfo,
+      credits,
+      rollupStatus,
+      error,
+      canManageKeys,
+      currentKeyRelation,
+    );
   } catch (error_) {
     const err = error_ as Error;
     error =
@@ -400,7 +508,7 @@ async function showAccountOverlay(ctx: ExtensionContext) {
       ? computeRollupStatus(keyInfo)
       : { status: 'unavailable' as const };
 
-    await showAccountOverlayComponent(ctx, keyInfo, credits, rollupStatus, error);
+    await showAccountOverlayComponent(ctx, keyInfo, credits, rollupStatus, error, false);
   }
 }
 
@@ -410,6 +518,8 @@ async function showAccountOverlayComponent(
   credits: number | null,
   rollupStatus: RollupStatus,
   error: string | null,
+  canManageKeys: boolean,
+  currentKeyRelation?: CurrentKeyRelation,
 ) {
   await ctx.ui.custom<void>(
     (_tui, theme, _keybindings, done) => {
@@ -422,6 +532,8 @@ async function showAccountOverlayComponent(
         done,
         () => _tui.requestRender(),
         ctx,
+        canManageKeys,
+        currentKeyRelation,
       );
 
       return {

package/extensions/openrouter/normalizers.ts

@@ -1,5 +1,11 @@
 import type { Model as SDKModel } from '@openrouter/sdk/models/index.js';
-import type { GetCurrentKeyData, ListData } from '@openrouter/sdk/models/operations/index.js';
+import type {
+  CreateKeysData,
+  GetCurrentKeyData,
+  GetKeyData,
+  ListData,
+  UpdateKeysData,
+} from '@openrouter/sdk/models/operations/index.js';
 import type { BYOKStatus, ResetCadence } from './account-types.js';
 import type { OpenRouterModel } from './models/types.js';
 
@@ -9,7 +15,7 @@ export interface NormalizedKeyMetadata {
   used: number;
   resetCadence: ResetCadence;
   byok: BYOKStatus;
-  hash: string;
+  hash?: string;
   disabled: boolean;
   limit?: number;
   remaining?: number;
@@ -83,7 +89,9 @@ export function normalizeOpenRouterModel(model: OpenRouterModel | SDKModel): Ope
  * Normalize SDK key metadata into the package's canonical internal shape.
  * Converts SDK null/variant fields once so account code can stay domain-focused.
  */
-export function normalizeSdkKeyMetadata(raw: GetCurrentKeyData | ListData): NormalizedKeyMetadata {
+export function normalizeSdkKeyMetadata(
+  raw: GetCurrentKeyData | ListData | GetKeyData | CreateKeysData | UpdateKeysData,
+): NormalizedKeyMetadata {
   const used = raw.usage ?? raw.usageMonthly ?? 0;
   const limit = raw.limit ?? undefined;
   const remaining = raw.limitRemaining ?? undefined;
@@ -96,10 +104,14 @@ export function normalizeSdkKeyMetadata(raw: GetCurrentKeyData | ListData): Norm
   }
 
   let resetCadence: ResetCadence = 'partial';
-  if (raw.limitReset) {
+  if (raw.limitReset === null) {
+    resetCadence = 'never';
+  } else if (raw.limitReset) {
     const reset = raw.limitReset.toLowerCase();
     if (reset === 'monthly') {
       resetCadence = 'monthly';
+    } else if (reset === 'weekly') {
+      resetCadence = 'weekly';
     } else if (reset === 'daily') {
       resetCadence = 'daily';
     } else if (reset === 'never') {
@@ -107,16 +119,21 @@ export function normalizeSdkKeyMetadata(raw: GetCurrentKeyData | ListData): Norm
     }
   }
 
+  const hash =
+    'hash' in raw && typeof raw.hash === 'string' && raw.hash.trim() !== '' ? raw.hash : undefined;
+
   const normalized: NormalizedKeyMetadata = {
     name: 'name' in raw ? (raw as ListData).name : raw.label,
     label: raw.label,
     used,
     resetCadence,
     byok,
-    hash: 'hash' in raw ? (raw as ListData).hash : 'unknown',
     disabled: 'disabled' in raw ? (raw as ListData).disabled : false,
   };
 
+  if (hash !== undefined) {
+    normalized.hash = hash;
+  }
   if (limit !== undefined) {
     normalized.limit = limit;
   }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
-  "description": "Live OpenRouter spend/account TUI overlays, user-scoped model sync, and session tagging for Pi.",
+  "description": "Live OpenRouter spend/account TUI overlays, user-scoped model sync, api key management, and session tagging for Pi.",
   "license": "MIT",
   "files": [
     "extensions",