@oh-my-pi/pi-ai 17.2.5 → 17.2.7

package/dist/types/registry/amazon-bedrock.d.ts

@@ -1,5 +1,11 @@
+import { resolveAwsRegistryApiKey } from "./aws.js";
 export declare const amazonBedrockProvider: {
     readonly id: "amazon-bedrock";
     readonly name: "Amazon Bedrock";
-    readonly envKeys: () => "<authenticated>" | undefined;
+    readonly envKeys: typeof resolveAwsRegistryApiKey;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        region: string | undefined;
+        profile: string | undefined;
+        bearerToken: string | undefined;
+    };
 };

package/dist/types/registry/aws.d.ts

@@ -0,0 +1,13 @@
+export interface AwsBedrockProviderOptions extends Readonly<Record<string, unknown>> {
+    /** AWS region used in the service endpoint and SigV4 credential scope. */
+    region?: string;
+    /** Named AWS shared-credentials/config profile. */
+    profile?: string;
+    /** Amazon Bedrock API key sent as a bearer token, ahead of SigV4 credential resolution. */
+    bearerToken?: string;
+}
+export declare function hasAwsCredentialSource(): boolean;
+/** Registry key marker for AWS transports that resolve their own bearer/IAM credentials. */
+export declare function resolveAwsRegistryApiKey(): string | undefined;
+/** Resolve a real AWS bearer token while filtering the registry's auth marker. */
+export declare function resolveAwsBearerToken(apiKey?: string, bearerToken?: string): string | undefined;

package/dist/types/registry/bedrock-mantle.d.ts

@@ -0,0 +1,22 @@
+import type { Model } from "../types.js";
+import { resolveAwsRegistryApiKey } from "./aws.js";
+export declare const bedrockMantleProvider: {
+    readonly id: "bedrock-mantle";
+    readonly name: "Amazon Bedrock Mantle";
+    readonly envKeys: typeof resolveAwsRegistryApiKey;
+    readonly allowsMissingApiKey: true;
+    readonly prepareRequest: (model: Model<import("@oh-my-pi/pi-catalog").Api>, options: import("../index.js").StreamOptions) => import("../providers/bedrock-mantle.js").PreparedBedrockMantleRequest;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        providerOptions: Readonly<Record<string, unknown>> | undefined;
+    };
+    readonly prepareModelDiscovery: (config: import("./types.js").ProviderModelDiscoveryConfig) => {
+        baseUrl?: string;
+        fetch?: import("@oh-my-pi/pi-utils").FetchImpl;
+        apiKey: undefined;
+        authenticated: false;
+    } | {
+        authenticated: true;
+        baseUrl: string;
+        fetch: import("@oh-my-pi/pi-utils").FetchImpl;
+    };
+};

package/dist/types/registry/registry.d.ts

@@ -25,7 +25,12 @@ declare const ALL: ({
 } | {
     readonly id: "amazon-bedrock";
     readonly name: "Amazon Bedrock";
-    readonly envKeys: () => "<authenticated>" | undefined;
+    readonly envKeys: typeof import("./aws.js").resolveAwsRegistryApiKey;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        region: string | undefined;
+        profile: string | undefined;
+        bearerToken: string | undefined;
+    };
 } | {
     readonly id: "anthropic";
     readonly name: "Anthropic (Claude Pro/Max)";
@@ -41,6 +46,25 @@ declare const ALL: ({
     readonly id: "baseten";
     readonly name: "Baseten";
     readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<string>;
+} | {
+    readonly id: "bedrock-mantle";
+    readonly name: "Amazon Bedrock Mantle";
+    readonly envKeys: typeof import("./aws.js").resolveAwsRegistryApiKey;
+    readonly allowsMissingApiKey: true;
+    readonly prepareRequest: (model: import("@oh-my-pi/pi-catalog").Model<import("@oh-my-pi/pi-catalog").Api>, options: import("../index.js").StreamOptions) => import("../providers/bedrock-mantle.js").PreparedBedrockMantleRequest;
+    readonly mapSimpleOptions: (options: import("../index.js").SimpleStreamOptions) => {
+        providerOptions: Readonly<Record<string, unknown>> | undefined;
+    };
+    readonly prepareModelDiscovery: (config: import("./types.js").ProviderModelDiscoveryConfig) => {
+        baseUrl?: string;
+        fetch?: import("@oh-my-pi/pi-utils").FetchImpl;
+        apiKey: undefined;
+        authenticated: false;
+    } | {
+        authenticated: true;
+        baseUrl: string;
+        fetch: import("@oh-my-pi/pi-utils").FetchImpl;
+    };
 } | {
     readonly id: "cerebras";
     readonly name: "Cerebras";

package/dist/types/registry/types.d.ts

@@ -9,6 +9,7 @@
  * (default model, model-manager factory, catalog discovery) lives in
  * `@oh-my-pi/pi-catalog`'s descriptor table.
  */
+import type { Api, FetchImpl, Model, SimpleStreamOptions, StreamOptions } from "../types.js";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types.js";
 /**
  * API-key environment fallback: either a single env var name (e.g.
@@ -16,6 +17,21 @@ import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types.js";
  * the host (Vertex ADC, Bedrock credential chains, …).
  */
 export type KeyResolver = string | (() => string | undefined);
+/** Credentials are resolved by the provider transport rather than used as a bearer string. */
+export declare const AUTHENTICATED_SENTINEL = "<authenticated>";
+export interface PreparedProviderRequest {
+    readonly model: Model<Api>;
+    readonly options: StreamOptions;
+}
+export type ProviderRequestPreparer = (model: Model<Api>, options: StreamOptions) => PreparedProviderRequest;
+export type ProviderSimpleOptionsMapper = (options: SimpleStreamOptions) => Readonly<Record<string, unknown>>;
+export interface ProviderModelDiscoveryConfig {
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    readonly fetch?: FetchImpl;
+    readonly authenticated?: boolean;
+}
+export type ProviderModelDiscoveryPreparer = (config: ProviderModelDiscoveryConfig) => ProviderModelDiscoveryConfig;
 /**
  * Declarative description of a single provider's auth/login wiring. All
  * fields are optional except `id`/`name`; presence of a field opts the
@@ -39,6 +55,14 @@ export interface ProviderDefinition {
     /** Whether to surface in the interactive login list. Defaults to true when `login` is present. */
     readonly showInLoginList?: boolean;
     readonly envKeys?: KeyResolver;
+    /** Provider transport can authenticate without a resolved API-key string. */
+    readonly allowsMissingApiKey?: boolean;
+    /** Provider-owned request shaping applied before generic API dispatch. */
+    readonly prepareRequest?: ProviderRequestPreparer;
+    /** Provider-owned projection from the generic simple-stream option bag. */
+    readonly mapSimpleOptions?: ProviderSimpleOptionsMapper;
+    /** Provider-owned authentication and endpoint setup for model discovery. */
+    readonly prepareModelDiscovery?: ProviderModelDiscoveryPreparer;
     readonly login?: (callbacks: OAuthLoginCallbacks) => Promise<OAuthCredentials | string>;
     readonly refreshToken?: (credentials: OAuthCredentials) => Promise<OAuthCredentials>;
     readonly getApiKey?: (credentials: OAuthCredentials) => string;

package/dist/types/types.d.ts

@@ -1,9 +1,9 @@
 export * from "@oh-my-pi/pi-catalog/effort";
 export * from "@oh-my-pi/pi-catalog/types";
+import type { Type } from "@oh-my-pi/omptype";
 import type { DeleteArgs, DeleteResult, DiagnosticsArgs, DiagnosticsResult, GrepArgs, GrepResult, LsArgs, LsResult, McpResult, PiBashExecArgs, PiBashExecResult, PiEditExecArgs, PiEditExecResult, PiFindExecArgs, PiFindExecResult, PiGrepExecArgs, PiGrepExecResult, PiLsExecArgs, PiLsExecResult, PiReadExecArgs, PiReadExecResult, PiWriteExecArgs, PiWriteExecResult, ReadArgs, ReadResult, ShellArgs, ShellResult, WriteArgs, WriteResult } from "@oh-my-pi/pi-catalog/discovery/cursor-gen/agent_pb";
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import type { Api, FetchImpl, Model, Provider, ThinkingBudgets, Usage } from "@oh-my-pi/pi-catalog/types";
-import type { Type } from "arktype";
 import type { ZodType, z } from "zod/v4";
 import type { ApiKey } from "./auth-retry.js";
 import type { BedrockOptions } from "./providers/amazon-bedrock.js";
@@ -124,10 +124,13 @@ export declare function serviceTierFamily(model: ServiceTierModel): ServiceTierF
 export declare function resolveModelServiceTier(tiers: ServiceTierByFamily | null | undefined, model: Pick<Model, "provider" | "api" | "id">): ServiceTier | undefined;
 /**
  * True when the tier should be sent on the wire as the provider's service-tier
- * request field. OpenAI / OpenAI-Codex accept every {@link ServiceTier};
- * Google (Gemini API + Vertex) and OpenRouter accept `flex`/`priority`;
- * Fireworks Serverless realizes only its Priority serving path. Anthropic is
- * absent because it realizes `priority` via `speed: "fast"`.
+ * request field. `auto` is never forwarded — it is OpenAI's implicit default, so
+ * omitting `service_tier` is identical to requesting `auto`, and the Codex
+ * (ChatGPT OAuth) endpoint rejects an explicit `auto` outright. OpenAI /
+ * OpenAI-Codex accept every other {@link ServiceTier}; Google (Gemini API +
+ * Vertex) and OpenRouter accept `flex`/`priority`; Fireworks Serverless
+ * realizes only its Priority serving path. Anthropic is absent because it
+ * realizes `priority` via `speed: "fast"`.
  */
 export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, target: Provider | ServiceTierModel | undefined): boolean;
 /**
@@ -249,6 +252,11 @@ export interface StreamOptions {
      * For example, Anthropic uses `user_id` for abuse tracking and rate limiting.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Provider-owned request configuration. Provider hooks interpret this bag;
+     * generic API transports do not forward its fields onto the wire.
+     */
+    providerOptions?: Readonly<Record<string, unknown>>;
     /** OpenAI Responses/Codex response fields to include verbatim. */
     include?: OpenAIResponseInclude[];
     /**

package/dist/types/usage.d.ts

@@ -206,125 +206,231 @@ export interface ClientUsageClientSummary {
 export interface ClientUsageSummary {
     clients: ClientUsageClientSummary[];
 }
-export declare const usageUnitSchema: import("arktype/internal/variants/string.ts").StringType<"bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd", {}>;
-export declare const usageStatusSchema: import("arktype/internal/variants/string.ts").StringType<"exhausted" | "ok" | "unknown" | "warning", {}>;
-export declare const usageWindowSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+export declare const usageUnitSchema: import("@oh-my-pi/omptype").FluentType<"bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd", "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd">;
+export declare const usageStatusSchema: import("@oh-my-pi/omptype").FluentType<"exhausted" | "ok" | "unknown" | "warning", "exhausted" | "ok" | "unknown" | "warning">;
+export declare const usageWindowSchema: import("@oh-my-pi/omptype").FluentType<{
+    durationMs?: number | undefined;
     id: string;
     label: string;
-    durationMs?: number | undefined;
+    resetLabel?: string | undefined;
     resetsAt?: number | undefined;
+}, {
+    durationMs?: number | undefined;
+    id: string;
+    label: string;
     resetLabel?: string | undefined;
-}, {}>;
-export declare const usageAmountSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    used?: number | undefined;
+    resetsAt?: number | undefined;
+}>;
+export declare const usageAmountSchema: import("@oh-my-pi/omptype").FluentType<{
     limit?: number | undefined;
     remaining?: number | undefined;
+    remainingFraction?: number | undefined;
+    unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+    used?: number | undefined;
     usedFraction?: number | undefined;
+}, {
+    limit?: number | undefined;
+    remaining?: number | undefined;
     remainingFraction?: number | undefined;
     unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
-}, {}>;
-export declare const usageScopeSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    provider: string;
+    used?: number | undefined;
+    usedFraction?: number | undefined;
+}>;
+export declare const usageScopeSchema: import("@oh-my-pi/omptype").FluentType<{
     accountId?: string | undefined;
-    projectId?: string | undefined;
-    orgId?: string | undefined;
     modelId?: string | undefined;
+    orgId?: string | undefined;
+    projectId?: string | undefined;
+    provider: string;
+    shared?: boolean | undefined;
     tier?: string | undefined;
     windowId?: string | undefined;
+}, {
+    accountId?: string | undefined;
+    modelId?: string | undefined;
+    orgId?: string | undefined;
+    projectId?: string | undefined;
+    provider: string;
     shared?: boolean | undefined;
-}, {}>;
-export declare const usageLimitSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    tier?: string | undefined;
+    windowId?: string | undefined;
+}>;
+export declare const usageLimitSchema: import("@oh-my-pi/omptype").FluentType<{
+    amount: {
+        limit?: number | undefined;
+        remaining?: number | undefined;
+        remainingFraction?: number | undefined;
+        unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+        used?: number | undefined;
+        usedFraction?: number | undefined;
+    };
     id: string;
     label: string;
+    notes?: string[] | undefined;
     scope: {
-        provider: string;
         accountId?: string | undefined;
-        projectId?: string | undefined;
-        orgId?: string | undefined;
         modelId?: string | undefined;
+        orgId?: string | undefined;
+        projectId?: string | undefined;
+        provider: string;
+        shared?: boolean | undefined;
         tier?: string | undefined;
         windowId?: string | undefined;
-        shared?: boolean | undefined;
     };
+    status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
     window?: {
+        durationMs?: number | undefined;
         id: string;
         label: string;
-        durationMs?: number | undefined;
-        resetsAt?: number | undefined;
         resetLabel?: string | undefined;
+        resetsAt?: number | undefined;
     } | undefined;
+}, {
     amount: {
-        used?: number | undefined;
         limit?: number | undefined;
         remaining?: number | undefined;
-        usedFraction?: number | undefined;
         remainingFraction?: number | undefined;
         unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+        used?: number | undefined;
+        usedFraction?: number | undefined;
     };
-    status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+    id: string;
+    label: string;
     notes?: string[] | undefined;
-}, {}>;
-export declare const usageResetCreditDetailSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    scope: {
+        accountId?: string | undefined;
+        modelId?: string | undefined;
+        orgId?: string | undefined;
+        projectId?: string | undefined;
+        provider: string;
+        shared?: boolean | undefined;
+        tier?: string | undefined;
+        windowId?: string | undefined;
+    };
+    status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+    window?: {
+        durationMs?: number | undefined;
+        id: string;
+        label: string;
+        resetLabel?: string | undefined;
+        resetsAt?: number | undefined;
+    } | undefined;
+}>;
+export declare const usageResetCreditDetailSchema: import("@oh-my-pi/omptype").FluentType<{
+    expiresAt?: string | undefined;
     grantedAt?: string | undefined;
+    status?: string | undefined;
+}, {
     expiresAt?: string | undefined;
+    grantedAt?: string | undefined;
     status?: string | undefined;
-}, {}>;
-export declare const usageResetCreditsSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+}>;
+export declare const usageResetCreditsSchema: import("@oh-my-pi/omptype").FluentType<{
     availableCount: number;
     credits?: {
+        expiresAt?: string | undefined;
         grantedAt?: string | undefined;
+        status?: string | undefined;
+    }[] | undefined;
+}, {
+    availableCount: number;
+    credits?: {
         expiresAt?: string | undefined;
+        grantedAt?: string | undefined;
         status?: string | undefined;
     }[] | undefined;
-}, {}>;
-export declare const usageReportSchema: import("arktype/internal/variants/object.ts").ObjectType<{
-    provider: string;
+}>;
+export declare const usageReportSchema: import("@oh-my-pi/omptype").FluentType<{
     fetchedAt: number;
     limits: {
+        amount: {
+            limit?: number | undefined;
+            remaining?: number | undefined;
+            remainingFraction?: number | undefined;
+            unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+            used?: number | undefined;
+            usedFraction?: number | undefined;
+        };
         id: string;
         label: string;
+        notes?: string[] | undefined;
         scope: {
-            provider: string;
             accountId?: string | undefined;
-            projectId?: string | undefined;
-            orgId?: string | undefined;
             modelId?: string | undefined;
+            orgId?: string | undefined;
+            projectId?: string | undefined;
+            provider: string;
+            shared?: boolean | undefined;
             tier?: string | undefined;
             windowId?: string | undefined;
-            shared?: boolean | undefined;
         };
+        status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
         window?: {
+            durationMs?: number | undefined;
             id: string;
             label: string;
-            durationMs?: number | undefined;
-            resetsAt?: number | undefined;
             resetLabel?: string | undefined;
+            resetsAt?: number | undefined;
         } | undefined;
+    }[];
+    metadata?: Record<string, unknown> | undefined;
+    notes?: string[] | undefined;
+    provider: string;
+    raw?: unknown;
+    resetCredits?: {
+        availableCount: number;
+        credits?: {
+            expiresAt?: string | undefined;
+            grantedAt?: string | undefined;
+            status?: string | undefined;
+        }[] | undefined;
+    } | undefined;
+}, {
+    fetchedAt: number;
+    limits: {
         amount: {
-            used?: number | undefined;
             limit?: number | undefined;
             remaining?: number | undefined;
-            usedFraction?: number | undefined;
             remainingFraction?: number | undefined;
             unit: "bytes" | "minutes" | "percent" | "requests" | "tokens" | "unknown" | "usd";
+            used?: number | undefined;
+            usedFraction?: number | undefined;
         };
-        status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+        id: string;
+        label: string;
         notes?: string[] | undefined;
+        scope: {
+            accountId?: string | undefined;
+            modelId?: string | undefined;
+            orgId?: string | undefined;
+            projectId?: string | undefined;
+            provider: string;
+            shared?: boolean | undefined;
+            tier?: string | undefined;
+            windowId?: string | undefined;
+        };
+        status?: "exhausted" | "ok" | "unknown" | "warning" | undefined;
+        window?: {
+            durationMs?: number | undefined;
+            id: string;
+            label: string;
+            resetLabel?: string | undefined;
+            resetsAt?: number | undefined;
+        } | undefined;
     }[];
+    metadata?: Record<string, unknown> | undefined;
+    notes?: string[] | undefined;
+    provider: string;
+    raw?: unknown;
     resetCredits?: {
         availableCount: number;
         credits?: {
-            grantedAt?: string | undefined;
             expiresAt?: string | undefined;
+            grantedAt?: string | undefined;
             status?: string | undefined;
         }[] | undefined;
     } | undefined;
-    notes?: string[] | undefined;
-    metadata?: {
-        [x: string]: unknown;
-    } | undefined;
-    raw?: unknown;
-}, {}>;
+}>;
 /** Optional logger for usage fetchers. */
 export interface UsageLogger {
     debug(message: string, meta?: Record<string, unknown>): void;

package/dist/types/utils/aws-profile.d.ts

@@ -0,0 +1,17 @@
+/** INI sections with `profile ` / `sso-session ` prefixes normalized. */
+export type AwsIniFile = Record<string, Record<string, string>>;
+export declare function parseAwsIni(text: string): AwsIniFile;
+/** Resolve the selected shared-credentials profile. */
+export declare function resolveAwsProfile(profile?: string): string;
+/**
+ * Whether the shared config file participates in profile/region resolution.
+ * Explicit profile selection enables it; the implicit default profile follows
+ * the AWS SDK's `AWS_SDK_LOAD_CONFIG` opt-in.
+ */
+export declare function shouldLoadAwsSharedConfig(profile?: string): boolean;
+export declare function resolveAwsProfileRegion(profile?: string): string | undefined;
+/** Region selected by the environment or active shared-config profile. */
+export declare function resolveAwsAmbientRegion(profile?: string): string | undefined;
+/** Resolve the region precedence shared by AWS transports and credential exchanges. */
+export declare function resolveAwsRegion(explicitRegion?: string, profile?: string): string;
+export declare function hasConfiguredAwsProfile(profile?: string): boolean;

package/dist/types/utils/schema/wire.d.ts

@@ -10,7 +10,7 @@
  * All three are normalized at the boundary so providers and validators see the same
  * JSON Schema dialect.
  */
-import type { Type } from "arktype";
+import type { Type } from "@oh-my-pi/omptype";
 import { type ZodType } from "zod/v4";
 import type { Tool } from "../../types.js";
 /**

package/dist/types/utils/validation.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Tool-call argument validation pipeline.
+ *
+ * Tools may declare their parameters as either Zod schemas (canonical) or
+ * plain JSON Schema (legacy / extensions). This module is the single
+ * entrypoint the agent calls before dispatching a tool — it:
+ *
+ *   1. Builds (or fetches from cache) a `ValidationContext` for the tool —
+ *      the Zod schema if available plus the equivalent wire JSON Schema, or
+ *      just the JSON Schema for non-Zod tools.
+ *   2. Normalizes LLM quirks (null / "null" → omit-or-default substitution)
+ *      against the JSON Schema before validation.
+ *   3. Validates with the Zod or JSON-Schema validator.
+ *   4. On failure, walks the resulting issues and coerces common LLM type
+ *      drift (JSON-stringified values, boolean/number/string scalar drift),
+ *      drops unrecognized keys, and retries up to `MAX_COERCION_PASSES` times.
+ *   5. Throws a formatted error if reconciliation fails; otherwise returns
+ *      the parsed arguments with original unknown root fields preserved (so
+ *      hallucinated top-level keys still surface to the caller).
+ *
+ * The goal is to be conservative: every coercion is a structural rewrite that
+ * keeps the schema in charge of acceptance — we never invent values, only
+ * massage shapes the LLM almost got right.
+ */
 import type { Tool, ToolCall } from "../types.js";
 /**
  * Finds a tool by name and validates the tool call arguments against its schema.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.2.5",
+	"version": "17.2.7",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,10 +38,10 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-catalog": "17.2.5",
-		"@oh-my-pi/pi-utils": "17.2.5",
-		"@oh-my-pi/pi-wire": "17.2.5",
-		"arktype": "2.2.3",
+		"@oh-my-pi/omptype": "17.2.7",
+		"@oh-my-pi/pi-catalog": "17.2.7",
+		"@oh-my-pi/pi-utils": "17.2.7",
+		"@oh-my-pi/pi-wire": "17.2.7",
 		"zod": "^4"
 	},
 	"devDependencies": {

package/src/auth-broker/client.ts

@@ -5,8 +5,9 @@
  * `omp auth-broker status` (liveness checks). All endpoints except
  * `/v1/healthz` require a bearer token.
  */
+
+import { type } from "@oh-my-pi/omptype";
 import { readSseEvents } from "@oh-my-pi/pi-utils";
-import { type } from "arktype";
 import type { AuthCredential, DisabledCredentialSummary } from "../auth-storage";
 import type {
 	ClientUsageReportRequest,

package/src/auth-broker/server.ts

@@ -9,8 +9,9 @@
  * Transport security is delegated to the operator (Tailscale / Wireguard);
  * the server only checks a bearer token against an allow-list per request.
  */
+
+import { type Type, type } from "@oh-my-pi/omptype";
 import { logger } from "@oh-my-pi/pi-utils";
-import { type Type, type } from "arktype";
 import type { AuthStorage, StoredCredentialBlock } from "../auth-storage";
 import { parseBind } from "../utils/parse-bind";
 import { AuthBrokerRefresher, type AuthBrokerRefresherSchedule } from "./refresher";

package/src/auth-broker/wire-schema-resource.ts

@@ -12,7 +12,7 @@
  * exception (standard type keeps extra keys): it preserves provider-specific extension fields so
  * they round-trip through the broker instead of being dropped (see below).
  */
-import { type Type, type } from "arktype";
+import { type Type, type } from "@oh-my-pi/omptype";
 import {
 	type ApiKeyCredential,
 	type AuthCredential,

package/src/dialect/examples.ts

@@ -15,17 +15,12 @@ export function renderToolExamples(tool: InbandTool, intentField?: string): stri
 	const examples = tool.examples;
 	if (!examples?.length) return "";
 	const renderCall = (args: Record<string, unknown>): string => {
-		let soleKey: string | undefined;
-		let argCount = 0;
-		for (const key in args) {
-			argCount++;
-			soleKey = key;
-		}
-		if (argCount === 1 && soleKey !== undefined && typeof args[soleKey] === "string") {
+		const bare = bareStringArg(args);
+		if (bare !== undefined) {
 			// Bare payload. The intent placeholder still rides on the envelope so
 			// intent-traced schemas (where `i` is required) keep teaching it.
 			const intentAttr = intentField ? ` ${intentField}="${INTENT_PLACEHOLDER}"` : "";
-			return `<example${intentAttr}>\n${args[soleKey]}\n</example>`;
+			return `<example${intentAttr}>\n${bare}\n</example>`;
 		}
 		// When intent tracing injects `i` into the schema, examples must show a
 		// placeholder so the model learns to emit it. Keep it first, matching the
@@ -43,3 +38,34 @@ export function renderToolExamples(tool: InbandTool, intentField?: string): stri
 	});
 	return `<examples>\n${parts.join("\n")}\n</examples>`;
 }
+
+/**
+ * Render a tool's examples as JSDoc-style `@example` lines for comment-gutter
+ * contexts (the Harmony `namespace functions` inventory): `@example "caption"`
+ * followed by the call in the same Python kwargs syntax as the wire block. The
+ * tag line delimits each example, so no XML envelope is needed — which is why
+ * the inventory uses this instead of `//`-prefixing the `<examples>` block.
+ */
+export function renderToolExamplesJsdoc(tool: InbandTool): string {
+	const examples = tool.examples;
+	if (!examples?.length) return "";
+	const renderCall = (args: Record<string, unknown>): string => bareStringArg(args) ?? pyCall(tool.name, args);
+	const parts = examples.map(ex => {
+		const head = ex.caption ? `@example ${JSON.stringify(ex.caption)}` : "@example";
+		if ("call" in ex) return `${head}\n${renderCall(ex.call)}`;
+		if ("good" in ex) return `${head}\nWRONG:\n${renderCall(ex.bad)}\nRIGHT:\n${renderCall(ex.good)}`;
+		return ex.note ? `${head}\n${ex.note}` : head;
+	});
+	return parts.join("\n");
+}
+
+/** Sole-argument string payload, if the call has exactly one string argument. */
+function bareStringArg(args: Record<string, unknown>): string | undefined {
+	let sole: unknown;
+	let count = 0;
+	for (const key in args) {
+		count++;
+		sole = args[key];
+	}
+	return count === 1 && typeof sole === "string" ? sole : undefined;
+}

package/src/dialect/inventory.ts

@@ -1,5 +1,5 @@
 import { jsonSchemaToTypeScript, toolWireSchema } from "../utils/schema";
-import { renderToolExamples } from "./examples";
+import { renderToolExamplesJsdoc } from "./examples";
 import type { InbandTool } from "./types";
 
 /**
@@ -18,7 +18,7 @@ export function renderToolInventory(tools: readonly InbandTool[]): string {
 		if (description) {
 			for (const line of description.split("\n")) lines.push(`// ${line}`.trimEnd());
 		}
-		const examples = renderToolExamples(tool);
+		const examples = renderToolExamplesJsdoc(tool);
 		if (examples) {
 			if (description) lines.push("//");
 			for (const line of examples.split("\n")) lines.push(`// ${line}`.trimEnd());